> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens and refresh

> Exchange codes, renew access, and revoke OAuth credentials.

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.

```bash theme={null}
curl --request POST https://api.ofauth.com/v3/link/token \
	--user "$OFAUTH_CLIENT_ID:$OFAUTH_CLIENT_SECRET" \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'grant_type=authorization_code' \
	--data-urlencode "code=$CODE" \
	--data-urlencode "redirect_uri=$OFAUTH_REDIRECT_URI" \
	--data-urlencode "code_verifier=$VERIFIER"
```

Successful code exchanges always return a refresh token for this confidential-client profile. No `offline_access` scope or proprietary flag is required.

```json theme={null}
{
  "access_token": "<opaque access token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "<opaque refresh token>",
  "scope": "identity:read profile:read",
  "authorization_id": "<authorization identifier>"
}
```

| Field | Meaning |
| - | - |
| `access_token` | Opaque Bearer secret. Do not decode it. |
| `token_type` | `Bearer`. |
| `expires_in` | Access-token lifetime in seconds. Use this value to calculate expiry. The initial lifetime is 15 minutes. |
| `refresh_token` | Stable secret bound to the authenticated client and renewable credential. |
| `scope` | Space-separated granted scopes, which can be fewer than requested. |
| `authorization_id` | Optional informational extension. Adapters need not retain it. |

Store credentials privately under the application customer who started the flow. Discover accounts through [`GET /v3/linked-accounts`](https://docs.ofauth.com/v3/api-reference/account/linked-accounts), then select one explicitly. Account lists are not a required token-response extension.

## Refresh the access token

```bash theme={null}
curl --request POST https://api.ofauth.com/v3/link/token \
	--user "$OFAUTH_CLIENT_ID:$OFAUTH_CLIENT_SECRET" \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'grant_type=refresh_token' \
	--data-urlencode "refresh_token=$REFRESH_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](https://github.com/ofauth-source/example-express-oauth) 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

```bash theme={null}
curl --request POST https://api.ofauth.com/v3/link/revoke \
	--user "$OFAUTH_CLIENT_ID:$OFAUTH_CLIENT_SECRET" \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode "token=$REFRESH_TOKEN" \
	--data-urlencode 'token_type_hint=refresh_token'
```

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}`](https://docs.ofauth.com/v3/api-reference/account/linked-accounts#remove-a-linked-account). [Reconnect](https://docs.ofauth.com/v3/guides/reconnect.md) 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.

| Field | Value |
| - | - |
| `issuer` | `https://api.ofauth.com/v3/link` |
| `authorization_endpoint` | `https://link.ofauth.com/v3/authorize` |
| `token_endpoint` | `https://api.ofauth.com/v3/link/token` |
| `revocation_endpoint` | `https://api.ofauth.com/v3/link/revoke` |
| `userinfo_endpoint` | `https://api.ofauth.com/v3/link/userinfo` |
| `response_types_supported` | `["code"]` |
| `grant_types_supported` | `["authorization_code", "refresh_token"]` |
| `code_challenge_methods_supported` | `["S256"]` |
| `token_endpoint_auth_methods_supported` | `["client_secret_basic", "client_secret_post"]` |
| `revocation_endpoint_auth_methods_supported` | `["client_secret_basic", "client_secret_post"]` |

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`.

| Error | Meaning |
| - | - |
| `invalid_request` | Missing, repeated, or malformed parameters, wrong encoding, or ambiguous authentication. |
| `invalid_client` | Missing or invalid client authentication, or an unavailable client. |
| `invalid_grant` | Expired, revoked, or mismatched credential; used or expired code; invalid PKCE. |
| `invalid_scope` | Unknown scope or permission expansion. |
| `unsupported_grant_type` | A grant other than authorization code or refresh token. |
| `invalid_target` | Unsupported resource audience. |
| `rate_limited` | Wait for `Retry-After` before retrying. |
| `server_error` | Temporary server failure. Retry refresh with bounded backoff. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.