Tokens

Lifetimes

TokenLifetime
Authorization code60 seconds, single use
Access token1 hour (expires_in, in seconds)
Refresh token90 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). 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:

{
  "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 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 shows it.

What happens when a refresh token is sent again:

SituationResult
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 useA 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 usedinvalid_grant, and the sign-in ends.
Two refreshes with the same refresh token race, or a retry overtakes its original requestBoth 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 revokedinvalid_grant (the revocation still answers 200), and the sign-in ends.
A spent refresh token is presented more than 30 seconds after its first useinvalid_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, however many tabs the user has open. The backend can hold a secret or use PKCE alone; see Getting access. Code samples 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.

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 lists what ends a sign-in.