# Tokens

## Lifetimes

| Token | Lifetime |
|---|---|
| Authorization code | 60 seconds, single use |
| Access token | 1 hour (`expires_in`, in seconds) |
| Refresh token | 90 days, sliding (each refresh returns a new one good for 90 days) |

Use the access token on API calls. When it expires, use the refresh token
to get a new pair, unless the sign-in has ended (see
[Revocation](/documentation/developers/revocation/)). We look each token up
on every call, so a revocation takes effect on your next request. A script
signs in once; save the new refresh token
every time, and expect to sign in again after 90 days without a refresh.

## Formats

Tokens are opaque: don't parse them. An access token starts with `pcc_at_`
and a refresh token with `pcc_rt_`, each 50 characters today.
`pca_subject` is a random UUID in its usual lowercase, hyphenated form, so
it says nothing about the user.

## The token response

A code exchange and a refresh answer with the same fields, with
`Cache-Control: no-store`:

```json
{
  "access_token": "pcc_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "pcc_rt_...",
  "scope": "compute:build compute:analyze compute:air",
  "pca_subject": "b6f2c9de-1234-4a11-9abc-9e6f7d3c2a10"
}
```

After a refresh, the access token you held before keeps working until it
expires, at most an hour later.

`scope` is the scopes the user approved in this sign-in that your app may
still use. It never grows on a refresh. It shrinks if we lower your app's
scope limit, and your existing access tokens lose that scope at the same
time. Read `scope` from every response rather than remembering the first
one.

## Refresh tokens rotate

Every time you use a refresh token, we return a **new** refresh token,
and the old one is spent. Save the new pair before you use it.

**Make one refresh at a time per sign-in, and keep the pair from the
latest response.** Share the refresh in flight with every request or thread
that needs it, and never go back to an older pair. Retry a refresh only
once the first attempt has failed, never while it may still arrive, as
after a timeout of your own. [Code
samples](/documentation/developers/code-samples/#refresh) shows one way.

**On a backend with several servers,** sharing the refresh within one
process isn't enough. Take a lock for the sign-in in your datastore
around the refresh: a row lock (`SELECT ... FOR UPDATE`) or an advisory
lock. Once you hold it, read the stored pair again, and if another
server refreshed while you waited, use its pair instead of refreshing.
[Code samples](/documentation/developers/code-samples/#on-several-servers)
shows it.

What happens when a refresh token is sent again:

| Situation | Result |
|---|---|
| A refresh's response was lost (a dropped connection, a crash before you saved it), and you send the same refresh token again within 30 seconds of its first use | A fresh, working pair for the same sign-in. We revoke any pair we returned for it before, so only the newest is live. |
| The same retry, after a refresh token from one of those earlier pairs has been used | `invalid_grant`, and the sign-in ends. |
| Two refreshes with the same refresh token race, or a retry overtakes its original request | Both get a pair, as for a lost response and its retry, and the first pair is revoked at once. If you keep the first pair, its refresh token ends the sign-in when used, as in the next row. |
| A refresh token that a retry replaced is presented or revoked | `invalid_grant` (the revocation still answers `200`), and the sign-in ends. |
| A spent refresh token is presented more than 30 seconds after its first use | `invalid_grant`, and the sign-in ends. |

A sign-in ends in those rows because we can't tell your app from someone
who stole the refresh token. When it ends, your next call with any token
from it gets `401`. The user's sign-ins on other devices aren't affected.

## Several devices

Each time a user approves your app, a new **sign-in** starts: its own
code, access and refresh tokens, and its own scopes, the ones approved
in it. A phone and a tablet can hold different scopes. A sign-in's
scopes never grow: refreshing keeps them, and a `scope` parameter on a
refresh is ignored. To get a scope a sign-in doesn't have, send the user
through authorization again, asking for it. That starts another sign-in
and ends none.

A user holds at most 10 live sign-ins with your app. The approval that
would start an eleventh ends the least recently used one, by its last
approval, code exchange or refresh. Keep tokens
per device or install, and expect a `401` and then `invalid_grant` on a
device that has been idle while the user signed in elsewhere.

`pca_subject` is the same across all of a user's sign-ins, so use it to
recognize the same user on another device.

## Storage

Treat both tokens as bearer credentials: anyone who has one can use it
until it expires or is revoked.

### Browser apps

Keep the tokens on a backend. A web app with a server of its own makes the
PCA calls from there: the backend runs the code exchange and the refreshes,
keeps the token pair in its own datastore, and gives the browser only a
session of your own (an HttpOnly cookie). The browser never sees a refresh
token, and the backend makes [one refresh at a time](#refresh-tokens-rotate),
however many tabs the user has open. The backend can hold a secret or use
PKCE alone; see [Getting
access](/documentation/developers/getting-access/#secrets). [Code
samples](/documentation/developers/code-samples/#on-a-backend) shows the
backend's side.

A browser app with no backend holds the tokens itself, in memory or
`sessionStorage`, never `localStorage`, and each tab signs in on its own:
tabs can't share one sign-in's refresh token, and a duplicated tab starts
with a copy of its original's `sessionStorage`, so don't copy a pair
between tabs.

### iOS and Android

Keep the tokens in the Keychain on iOS, and encrypted with a key in the
Android Keystore on Android. Never put them in plain preferences, shared
storage or logs. How your app opens the authorization request matters too:
see [Mobile and desktop
apps](/documentation/developers/authorization-flow/#mobile-and-desktop-apps).

## Revoke on logout

When a user logs out of your app, revoke the sign-in's refresh token
instead of only discarding your tokens:

```
POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<refresh_token>&client_id=<your client ID>
```

Send the secret if the sign-in was made with one. Revoking ends this
device's sign-in only; the user's other devices stay signed in.
[Revocation](/documentation/developers/revocation/) lists what ends a
sign-in.
