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). 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:
| 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, 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.