Application integration workflow

This guide explains how to integrate GoodVision login, then add APIs, events and commerce as needed. For login only, create an Application, enter the callback and copy configuration, then verify login.

Before you start

Sign in to the Developer Console for the current environment. An account with no enterprise gets a personal space automatically and can create an Application there. Its creator becomes the Application owner without preparing business roles. Join an existing enterprise and obtain Application access when collaborating on its Applications. Prepare a product name and an implemented login callback such as https://app.example.test/auth/callback.

One independent product in one environment uses one Application. User login and backend calls use two identities within that Application. Sandbox and Production use separate Applications. To correlate users across products, see Applications, users and events.

Integrate user login in three steps

Step 1: Create an Application

Enter the Application name and create it. Sandbox is the default and the application code is generated automatically; expand advanced settings only to customize it. Check the environment and integration status on the credentials page. Successful automatic configuration returns active. Follow the displayed recovery action for a dependency failure rather than creating a duplicate.

Step 2: Enter the callback and copy configuration

Open “Development integration → OAuth/OIDC configuration → User identity”, confirm that user identity is enabled, and enter the exact callback. The platform provisions and validates login configuration for this Application. Save, then copy its non-sensitive configuration.

Configuration	Requirement	Description
Callback URL	🔴 Required	Exact implemented route that receives the authorization code
Logout URL	Optional	Check the suggested return address; omit if post-logout redirection is unused
Web Origin	Optional	Scheme, host and port; adjust only for browser requests that need it
Issuer and Client ID	Platform-provided	Required for integration; copy from this Application
Client Secret	Not applicable to user identity	Required only for backend application identity

For https://app.example.test/auth/callback, the origin is https://app.example.test and the logout return can be https://app.example.test/. A product entry URL and a login callback serve different purposes.

Step 3: Implement the callback and verify login

Implement Authorization Code + PKCE, callback validation and your own session on the application server. Verify the exact callback, session refresh and logout, as well as rejection of invalid tokens and wrong Applications. See Authentication and authorization.

After login, call User and customer space with {} on first entry. The platform prepares or reuses a personal space and returns the current user, space and membership. No Group or fixed customer organization ID is required.

Login alone requires no business API Subscription, webhook or subscription plan. Identity and membership do not grant paid entitlements or product permissions.

Add APIs as needed (optional)

Use application identity for background jobs and user identity for actions after login. Each identity has its own OAuth client, scopes and API authorization. See Integration entry points and permissions.

1. Open “APIs and permissions” for this Application and confirm the calling identity.
2. Select the APIs your product uses and least-privilege scopes. Do not hand-build unpublished scopes.
3. Save. The platform validates ownership, identity and permissions automatically and enables valid configuration without human review.
4. Call one read-only operation at the Base URL supplied by that API Product. Verify token, audience, scope and customer boundary acceptance and denial.

Only application identity requires a Client Secret. The Application Owner can reveal or rotate it according to the current status in “Credentials and basic information”; approved secure delivery may also be used. Keep Secrets server-side, outside ordinary configuration exports, logs and caches. Source code, internal hostnames and sample placeholder paths are not callable addresses.

Receive business events (optional)

Applications without events do not need a receiver configuration. To receive events, open “Developer integration → Events and webhooks”, select the event types you consume and save.

Transport	Required configuration	Next step
Long connection (recommended)	Current Application identity, Client Secret and event set; no public receiver URL	Run the Node.js 22 example and ACK after processing
HTTPS Webhook	Public HTTPS URL, endpoint verification and signing configuration	Follow Receive webhooks, persist receipt and return 2xx
Synchronous callback (optional)	Separate callback set, verified HTTPS URL and structured response	Return a result within five seconds; no automatic retries

Both asynchronous transports require Application, environment and customer checks, event_id deduplication and resource-version handling. Test disconnects, timeouts and duplicate deliveries. Queuing a test does not prove receipt; inspect delivery logs and receiver results.

Correlate subscriptions by Application, environment, customer space and subscription ID; correlate member events by membership_id. See Applications, users and events.

Add subscriptions and payments (optional)

To charge through the platform, configure integration capabilities, publish plans and prepare the purchase entry. Login configuration, API authorization, commercial availability and customer entitlements are verified separately. See Third-party SaaS billing.

Sandbox acceptance checklist

Check	Expected result
Application and environment	Selected capabilities belong to the correct developer, Application and environment; unselected capabilities do not block login
Login	Exact callback, refresh and logout succeed; user identity requires no Secret
User and space	First entry, concurrent calls and re-entry reuse the personal space; invalid selections never switch silently and 503 is recoverable
Selected APIs	Positive and negative tests cover audience, scope, customer and resource permissions
Selected events	Signature, scope, deduplication, ordering, durable ACK and recovery pass
Commands and credentials	Stable Idempotency-Key; no tokens or Secrets in logs, tickets or email

Prepare Production and launch

1. Develop and run applicable tests in Sandbox. Record actual results; platform configuration validation does not perform your application tests.
2. Create independent Production configuration in Developer integration → Sandbox and launch. Current Sandbox acceptance is not a prerequisite, and creation does not enable production operation. Credentials, consent, business data and review results are not copied across environments.
3. Configure the login, APIs, events, publication details and availability your Production application needs. In Application → Versions, save a draft and include references to the tests for this configuration.
4. Explicitly submit for launch review. An independent reviewer checks the whole version; applicants cannot approve their own application. After rejection, change the configuration and create a new version.
5. Explicitly publish the approved version. Publication rechecks resources and current access before updating production entries together. New drafts and pending reviews preserve the existing published version.

Development-only applications do not need a marketplace listing. Launch review applies to the actual private, selected-customer or public distribution scope. Commercial prices, payments and customer entitlements retain their own authorization rules.

Recover unknown results with the original operation. Read the current version and publication state after a revision conflict. Sign-in recovery never automatically submits or publishes. See Application versions.