Your app’s Authentication Method determines what users must do during installation to grant your app access to their account. Orceum manages the entire credential lifecycle — collection, encryption, injection, refresh, and revocation. You configure these settings directly in the Orceum Developer Studio when creating or editing your app.

​
Comparison

Auth MethodInstallation UXCredentials Injected On CallUse When
NoneInstant — no stepsNothing extraPublic APIs, internal tools
API KeyUser pastes a keyAuthorization: Bearer <key> (or custom header)Services with API keys
OAuth 2.0OAuth consent screen redirectAuthorization: Bearer <access_token>Services with OAuth 2.0

​
None (No Authentication)

The simplest option. Select None in the Developer Studio. Installation completes instantly with no user input. Use when: Your app doesn’t need per-user credentials (public APIs, tools with their own access control, internal services).

​
API Key Authentication

Users provide an API key during installation. Select API Key in the Developer Studio. Orceum encrypts the key and injects it on every subsequent action call. Installation flow:
  1. User installs → Orceum prompts: “Enter your API key”
  2. Optionally, provide instructions and a format hint in the Developer Studio to guide the user.
  3. User submits key → validated (min 8 chars) → encrypted and stored.
  4. Every action call includes the key in your configured header.

​
Configuration Fields

When you select API Key authentication, you will configure how the key is sent to your app:
  • Header Name: The HTTP header name that carries the API key. Common values: Authorization, X-API-Key, Api-Key.
  • Header Prefix: A prefix added before the key value. For Bearer, the header becomes: Authorization: Bearer sk-abc123. Leave empty for no prefix.
  • Key Location: Where to put the key: Header (default) or Query Parameter. If Query Parameter, the key is added to the URL instead of a header: ?X-API-KEY=sk-abc123.

​
Examples

If your API expects Authorization: Bearer sk-abc123:
  • Header Name: Authorization
  • Header Prefix: Bearer
  • Key Location: Header

​
OAuth 2.0

Full OAuth 2.0 Authorization Code flow, managed entirely by Orceum. Select OAuth in the Developer Studio. Orceum handles the redirect, code exchange, token storage, automatic refresh, and revocation. Installation flow:
  1. User installs → Orceum builds the authorization URL.
  2. User is redirected to your OAuth provider’s consent screen.
  3. User grants permissions.
  4. Provider redirects to Orceum’s callback URL.
  5. Orceum exchanges the code for access and refresh tokens.
  6. Tokens are encrypted at rest.
  7. Every action call includes: Authorization: Bearer <access_token>.
You must register this exact redirect URI with your OAuth provider:
https://api.orceum.com/v1/apps/{your_app_id}/oauth/callback

​
Token Lifecycle

  • Auto-refresh: Orceum automatically refreshes the access token before it expires using the refresh token.
  • 401 retry: If your app returns an HTTP 401 Unauthorized, Orceum attempts a token refresh and retries the request once.
  • Revocation: When a user uninstalls, Orceum calls your Revoke URL if you provided one.
  • Re-auth: If a token refresh fails, the user is prompted to re-authenticate via a secure link.
For Google OAuth, add these to your Additional Auth Parameters in the dashboard to ensure you get a refresh token: access_type: offline and prompt: consent.
For the complete OAuth configuration reference, see OAuth Deep Dive.