Authentication

Every request to the Refersion API is authenticated with a Bearer token in the Authorization header. For programmatic access you obtain that token by exchanging your Refersion account's OAuth client credentials (a Client ID and Client Secret) for an access token, then send the token on each API call. You choose between a one-hour and a 90-day token when you request it — see Step 2.

This guide walks through the full flow: generate credentials, exchange them for an access token, and call the API. The endpoints themselves are listed in the sidebar, grouped by resource.

Who authenticates

OAuth client credentials belong to a Refersion account, not to an individual person. A token issued from those credentials acts on behalf of the account that generated them and can reach only that account's data — a token never crosses account boundaries.

A client_credentials token is a machine credential: it identifies your application rather than a person signing in.

Step 1 — Get credentials

Generate an OAuth client from your account under Settings → Integrations → Refersion API Keys. In the OAuth section, choose Generate OAuth Client. Refersion issues a Client ID and a Client Secret — the two values you exchange for an access token in Step 2.

That same section lists every non-revoked OAuth client on your account with its currently live tokens, and is where you revoke a client you no longer use.

Save your Client Secret

The Client Secret is shown only once, at the moment the client is created. It cannot be retrieved later. Store it somewhere secure. If you lose it, generate a new OAuth client and update your integration with the new credentials.

Revoking is immediate and irreversible

Revoking an OAuth client invalidates the client and every access token issued to it, straight away. Any integration still using those credentials stops working and no further token can be issued for them. Revoking the client is the only way to kill a leaked token outright — individual tokens cannot be revoked on their own.

Step 2 — Exchange credentials for a token

Send a POST request to the /oauth/token endpoint. The endpoint accepts either form-encoded fields or a JSON body containing your client_id and your client_secret. This example uses form-encoded fields:

curl -X POST https://auth.refersion.com/oauth/token \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d token_type=long_lived

A successful response returns the access token and its lifetime:

{
  "token_type": "Bearer",
  "expires_in": 7776000,
  "access_token": "<access_token>"
}

Choosing a token lifetime

The optional token_type request parameter selects how long the issued token lives:

token_type	Lifetime	expires_in
short_lived	1 hour	3600
long_lived	90 days	7776000

Omitting token_type is the same as sending short_lived, so integrations built before this parameter existed are unaffected and keep receiving one-hour tokens.

Any other value — including an empty one — is rejected with an invalid_request error and no token is issued.

token_type means two different things here

The token_type you send in the request selects the lifetime (short_lived / long_lived). The token_type in the response is the OAuth 2.0 token class and is always "Bearer". They are unrelated fields that happen to share a name.

Read expires_in rather than assuming 3600. It is the authoritative lifetime in seconds for the token you were just issued, and it changes with token_type.

A new token replaces the previous one of the same type

A client can hold one live token of each type at a time. Requesting a long_lived token immediately revokes that client's previous long_lived token and leaves its short_lived token working, and vice versa. Roll credentials by requesting the replacement and switching to it — the old token of that type stops working the moment the new one is issued.

A 90-day token is convenient, but it also widens the window during which a leaked token stays usable. If one is exposed, revoke the whole client (Step 1) rather than waiting for expiry.

No refresh token is issued for the client_credentials grant — when a token expires, request a new one by repeating this step.

Step 3 — Call the API

Send the access token in the Authorization header, prefixed with Bearer, on every request to https://api.refersion.com/v2026-08:

curl https://api.refersion.com/v2026-08/offers \
  -H "Authorization: Bearer <access_token>"