OAuth and API keys #

This page is for application creators who connect programs to Exponential. There are three credentials; choose by who the program acts for.

Contents #

1. Which credential
2. OAuth2 for third-party applications
3. Personal API keys
4. expservices tokens
5. Good practice

Which credential #

OAuth2 for third-party applications #

1. An administrator registers the client in Setup > oAuth admin (/oauthadmin/list): identifier, secret, redirect address.
2. The app sends the user to /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&state=..., with PKCE also code_challenge=...&code_challenge_method=S256; the user signs in and allows it, and the site redirects back with the code and the same state. The user needs the policy oauth/authorize (optionally limited by siteaccess); without it the site redirects with error=access_denied (OAuth authorize policy).
3. The app exchanges the code at POST /api/auth/v1/oauth/token (grant_type=authorization_code, and code_verifier when it sent a challenge).
4. It sends Authorization: OAuth <token> (a token in the address, ?oauth_token=, is refused unless rest.ini [OAuthSettings] AllowTokenInQuery=enabled); after TokenTTL (one hour by default) it uses grant_type=refresh_token. A refresh token lasts RefreshTokenTTL (30 days by default) from the refresh that issued it (OAuth token hardening).

The client secret belongs on a server. An app that cannot keep a secret (a mobile or browser app) is a public client: it is stored without a secret, sends none and must use PKCE with S256 (PKCE and state). A page in a browser on another host reaches the API only when CORS is switched on for its origin (CORS for the REST API; off by default).

Personal API keys #

• A user with apikey/create makes keys in My account > API access (/apikey/list), with scopes and a lifetime; the key expk_... is shown once.
• Requests with Authorization: Bearer expk_... run as the owner, limited to the key's scopes and never beyond the owner's policies.
• Only a salted HMAC of the secret is stored. Keys end when revoked, expired, or when the owner is disabled.
• Administrators see and revoke every key in Setup > oAuth admin > API keys; every make, revoke, first use and refusal is in the audit trail as access.apikey.*.

expservices tokens #

expservices has its own personal tokens for its services, created per user; the guide walks through making one and calling services from shell and Python (Remote services and apps).

Good practice #

• One credential per program, so one can be revoked alone.
• Smallest scope and role that works; a dedicated user for integrations, not the administrator.
• Secrets in environment variables or a secret store; never in a repository, a URL or a log.
• Short lifetimes, rotation, and a check of the audit trail for refusals.

Related pages #

• REST API v1 and v2 for applications
• Access control in code
• API keys BC note
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.