Authenticate with OAuth 2.0 - ION Manual

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Use OAuth 2.0 when the caller is a user-facing application, such as a web app, desktop tool, or mobile client. OAuth lets ION enforce that user’s permissions rather than a service account’s. For system-to-system integrations, use an API key instead.

Register an OAuth application

Before users can sign in to your application, an org admin must register the application with ION. Run this mutation to register it:

mutation RegisterApp {
  registerOauthApp(name: "Acme Production Dashboard", appType: "regular_web") {
    oauthApp {
      id
      clientId
    }
  }
}

After registration, configure callback URLs, allowed origins, and logout URLs:

mutation AddCallback {
  addOauthRedirectUri(
    oauthAppId: 42
    uri: "https://app.example.com/auth/callback"
    uriType: "callback"
  ) {
    redirectUri {
      id
      uri
      uriType
    }
  }
}
}

Three URI types are supported:

Register every URL your application uses (production, staging, local development) to avoid redirect_uri mismatches.

Run the authorization code flow

Follow the standard OAuth 2.0 authorization code flow:

1. Redirect the user to the ION authorization endpoint. Include client_id, redirect_uri, response_type=code, scope, and state.
2. The user authenticates with their ION credentials or SSO.
3. ION redirects to your redirect_uri with an authorization code and the state you sent.
4. Exchange the code at the token endpoint for an access_token, and optionally a refresh_token.
5. Use the access token on subsequent API calls.

The authorization and token endpoint URLs depend on your org’s auth provider configuration. ION surfaces them in the OAuth app registration response. If you’re integrating against ION for the first time, ask your CSM for the endpoint values that match your environment.

Handle token expiration and refresh

Access tokens have a short lifetime, typically one hour. Two patterns handle expiration:

• Short-lived integrations. Let the token expire. Re-run the auth flow the next time the user opens the app.
• Long-lived integrations. Request the offline_access scope at authorization. Then exchange refresh tokens for new access tokens transparently.

Always re-validate tokens before relying on them. Clock skew, server-side revocation, or org membership changes can invalidate a token mid-flight.

Scopes

Scopes constrain what an OAuth-issued token can do. Standard scopes include the following:

ION applies the user’s existing role and permission grants on top of the scope. A scope cannot grant a user more access than their role allows.