When you select OAuth 2.0 as your authentication method, Orceum manages the entire token lifecycle: authorization redirect, code exchange, encrypted storage, automatic refresh, and revocation. You configure these settings directly in the OAuth section of the Orceum Developer Studio.

​
Endpoint Discovery

You can provide endpoint URLs directly, or let Orceum discover them automatically using standard discovery protocols:
  • Authorization URL: The provider’s authorization endpoint, e.g., https://accounts.google.com/o/oauth2/v2/auth.
  • Token URL: The provider’s token exchange endpoint, e.g., https://oauth2.googleapis.com/token.
  • Revoke URL (Optional): Token revocation endpoint. Called automatically when a user uninstalls your app.
  • OpenID Config URL (Optional): OpenID Connect discovery document URL, e.g., https://accounts.google.com/.well-known/openid-configuration. If provided, Orceum fetches the endpoints from here (overriding manual entries).
  • Authorization Server URL (Optional): OAuth 2.0 Authorization Server Metadata URL. Used as a fallback if the OpenID Config URL is not provided.
  • Server URL (Optional): Base URL for the provider. Orceum will append standard paths to attempt endpoint discovery.

​
Client Credentials

  • Client ID: Your app’s OAuth client ID from the provider.
  • Client Secret: Your app’s OAuth client secret. This is stored encrypted.
If you enable Dynamic Client Registration (DCR), leave the Client ID empty. Orceum will dynamically register your app and populate these credentials for you.

​
Authorization Flow

  • Scopes: A comma-separated list of OAuth scopes to request (e.g., read:user, write:data). Request only the scopes your app needs.
  • Use PKCE: Enable Proof Key for Code Exchange (PKCE). Recommended for public clients. When enabled, Orceum generates a code_verifier and code_challenge pair.
  • Additional Auth Params: Key-value pairs added to the authorization URL query string.
    • Google example (to get a refresh token on first consent): Key: access_type, Value: offline; Key: prompt, Value: consent
    • Slack example (for granular user scopes): Key: user_scope, Value: channels:read,users:read
  • Redirect URIs: You must register the following exact URI with your OAuth provider: 
    https://api.orceum.com/v1/apps/{your_app_id}/oauth/callback

​
Token Lifecycle Overrides

Some providers deviate from the standard OAuth 2.0 token response fields. You can override what Orceum looks for:
  • Token Expiry Field: The field name containing the expiry value in seconds. Default is expires_in.
  • Token Type Field: The field name describing the token type. Default is token_type.

​
Dynamic Client Registration (DCR)

If your provider supports RFC 7591 Dynamic Client Registration, you can enable Supports Dynamic Registration. When enabled, Orceum will register your app dynamically with the provider on first connection. On success, the backend automatically securely stores your newly issued client_id and client_secret. You do not need to provide them manually.

​
Token Lifecycle Managed by Orceum

Lifecycle EventWhat Orceum Does
New installationRedirects user → receives code → exchanges for access_token + refresh_token
Token nearing expiryAutomatically refreshes using refresh_token before the next action call
App returns 401Attempts token refresh, retries request once
Refresh failsMarks installation REAUTH_REQUIRED, prompts user to re-authenticate
User uninstallsCalls revoke_url (if configured) to invalidate tokens
Tokens are stored encrypted at rest using Fernet symmetric encryption.

​
Common Provider Configurations

  • Client ID: xxx.apps.googleusercontent.com
  • Client Secret: GOCSPX-...
  • OpenID Config URL: https://accounts.google.com/.well-known/openid-configuration
  • Scopes: openid, email, profile
  • Use PKCE: Enabled
  • Additional Auth Params:
    • access_type: offline
    • prompt: consent
Without the access_type: offline and prompt: consent additional parameters, Google will not return a refresh token after the first authorization.
  • Client ID: Ov23li...
  • Client Secret: your_client_secret
  • Authorization URL: https://github.com/login/oauth/authorize
  • Token URL: https://github.com/login/oauth/access_token
  • Scopes: repo, read:user, notifications
GitHub access tokens do not expire by default unless you explicitly opt into expiring tokens in your GitHub OAuth app settings.
  • Client ID: 1234567890.1234567890
  • Client Secret: your_client_secret
  • Authorization URL: https://slack.com/oauth/v2/authorize
  • Token URL: https://slack.com/api/oauth.v2.access
  • Scopes: channels:read, chat:write, users:read
  • Additional Auth Params:
    • user_scope: channels:read,users:read