mobius

Get started free
Get started free

API

Return embedded OAuth to your app

Products that embed Mobius can return the browser to their own application after a managed Gmail or Slack OAuth connection. The normal Mobius connection flow is unchanged when you omit return_url and client_state.

There is no allowlist management screen in the app. An organization Owner or Admin configures it through the organization API.

Allowlist your origin

Replace the complete origin allowlist with:

PUT /v1/organization/oauth-return-origins
Authorization: Bearer <admin-api-key>
Content-Type: application/json
 
{
  "origins": ["https://app.partner.example"]
}

Each entry is an exact HTTPS origin: scheme, host, and optional non-default port. Paths, query strings, fragments, and embedded credentials are not valid origins. Mobius lowercases hosts, strips default ports, removes duplicates, and accepts at most 20 entries. Sending an empty array disables embedded return.

Read the current normalized list with:

GET /v1/organization/oauth-return-origins

Start the connection

Add return_url and client_state to a supported connect request:

POST /v1/projects/platform/integrations/providers/gmail/connect
Authorization: Bearer <api-key>
Content-Type: application/json
 
{
  "return_url": "https://app.partner.example/settings/integrations/callback",
  "client_state": "connect_session_01J8"
}

Open the response's redirect_url in the user's browser when kind is redirect. The return URL may be up to 2,048 bytes. Its origin must exactly match an allowlisted origin, and it cannot include a fragment or credentials.

client_state is an opaque value of at most 512 bytes. Generate it in your backend, bind it to the signed-in user and connection attempt, and consume it once after the browser returns. client_state without return_url is invalid.

Embedded return is supported by managed Gmail OAuth and the managed Slack app. The customer-owned Slack app flow rejects these fields.

Handle the callback

Mobius appends a closed set of query fields to your return_url:

FieldWhen presentMeaning
outcomeAlwaysconnected, denied, or failed
providerAlwaysThe provider ID, such as gmail or slack
connection_idConnected onlyThe persisted Mobius integration ID
client_stateWhen suppliedYour opaque value, returned verbatim
correlation_idAlwaysIdentifier to give support when investigating the callback
error_codeDenied or failedStable code such as oauth_denied, oauth_failed, or invalid_state

For example:

https://app.partner.example/settings/integrations/callback?outcome=connected&provider=gmail&connection_id=int_123&client_state=connect_session_01J8&correlation_id=cor_456

Verify client_state before changing application state. On connected, store the connection ID or refresh the provider status from Mobius. On denied, let the user retry without treating the refusal as an application error. On failed, record the correlation_id and show a retry path.

Revocation and fallback behavior

Mobius signs the return context into provider OAuth state and validates the origin both when the connection starts and when the provider calls back. Removing an origin therefore revokes in-flight returns to that origin.

If Mobius cannot authenticate the state, the origin is no longer allowed, or the final redirect would exceed 4,096 bytes, the browser falls back to the Mobius application. Do not assume every started attempt will reach the partner callback; reconcile provider status when your own attempt expires.

Next