Skip to main content
OFAuth uses confidential backend clients, authorization code with S256 PKCE, opaque Bearer access tokens, and stable client-bound refresh tokens. Sandbox, Test, and Live use the same protocol.

Authenticate the client

Send application/x-www-form-urlencoded requests to POST https://api.ofauth.com/v3/link/token and POST https://api.ofauth.com/v3/link/revoke. Use one client authentication method per request:
  • client_secret_basic: send the client ID and secret in HTTP Basic authentication.
  • client_secret_post: send client_id and client_secret in the form body.
Missing authentication and requests that combine both methods are rejected. Keep secrets on your backend. Public clients, implicit, password, and client_credentials grants are unsupported.

Exchange the authorization code

Validate the callback’s state, initiating application user and session, expiry, single use, and issuer before exchanging its code. The redirect URI must match the authorization request exactly.
Successful code exchanges always return a refresh token for this confidential-client profile. No offline_access scope or proprietary flag is required.
Store credentials privately under the application customer who started the flow. Discover accounts through GET /v3/linked-accounts, then select one explicitly. Account lists are not a required token-response extension.

Refresh the access token

Each success returns a new access token and the same refresh token. Independent processes can refresh concurrently, and both access tokens remain valid. Retry a refresh after a lost response or failed access-token save. No distributed refresh lock, replay journal, or unknown-outcome re-consent is required. An optional scope can narrow the new access token. It cannot add permissions or change another instance’s renewable scope. Omitting it uses approved credential scopes intersected with current authorization and client policy. Refresh tokens expire after 90 days without a successful authenticated refresh. Resource requests do not extend that window. Revoked and expired credentials never revive. Guest expiry, owner authority, client restrictions, and disconnect can end access earlier. Keep normal stale-write protection: when a customer replaces or disconnects a registration, an earlier callback or refresh must not overwrite the new registration. The Express example uses application registration versions for this purpose. invalid_grant requires a new authorization. Temporary storage, network, or authority-service failures remain retriable. Never automatically repeat a provider write because its response was lost.

Revoke

RFC 7009 accepts token and optional token_type_hint (refresh_token or access_token). Both supported client authentication methods work here.
  • Revoking a refresh token ends that credential and all its access tokens.
  • Revoking an access token ends only that access token.
  • Unknown, already revoked, and foreign-client tokens return non-disclosing success without affecting another client.
  • Independent credentials remain usable. Credential revocation does not erase durable owner consent or emit whole-authorization revocation.
Success returns HTTP 200. To end the whole authorization and all its credentials, send DELETE https://api.ofauth.com/v3/authorization with its Bearer token, or let the owner disconnect your app in OFAuth. New admissions fail after committed revocation. Already dispatched side effects cannot be undone. To remove one account, use DELETE /v3/linked-accounts/{id}. Reconnect repairs an account’s provider session and does not renew OAuth or change consent.

Current authorization

GET https://api.ofauth.com/v3/authorization uses the current Bearer token and returns its authorization identity, effective scope, and a linked-account page. No account selector is required. Follow the linked-account resource API for subsequent pages. DELETE on the same route ends the whole authorization and all credentials. Repeating the effect is safe, but a later request with the dead Bearer can return invalid_token; the endpoint does not accept a revoked credential just to repeat a success response.

Discovery

GET https://api.ofauth.com/.well-known/oauth-authorization-server/v3/link publishes RFC 8414 authorization-server metadata. This is plain OAuth. OFAuth does not advertise OIDC discovery, ID tokens, or a public JWKS for this issuer. Configure explicit endpoints in adapters unless their RFC 8414 discovery behavior has been verified.

Token endpoint errors

OAuth endpoints return error and error_description. Token responses use Cache-Control: no-store. Client suspension denies new admissions. Routine client-secret rotation rejects the retired secret at OAuth endpoints without requiring existing customer tokens to end. An unavailable Developer plan is the application’s responsibility; the owner’s Operator plan does not govern Developer grants.