Code in

Token: refresh

Swaps a refresh token for a new access token and a new refresh token. The old refresh token stops working.

POST https://accounts.aton-network.org/oauth/token

When to use it

When an access token has expired (15 minutes) and you need userinfo again while the person is away.

Authentication

The same client authentication as the code swap.

Parameters

Name	In	Type	Required	Limits	What it is
`grant_type`	form	string	yes	refresh_token	This grant.
`refresh_token`	form	string	yes		The newest refresh token you hold.
`scope`	form	string	no		Fewer scopes than were granted, to narrow the new access token. Never more.
`client_id`	form	string	no		Required for a public app.

Request

# A new access token and a new refresh token for the newest refresh token you hold. The old one stops working.
curl https://accounts.aton-network.org/oauth/token \
  -u "$ATHERON_CLIENT_ID:$ATHERON_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

Response

http

HTTP 200
content-type: application/json
cache-control: no-store

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email offline_access",
  "refresh_token": "ath_rt_k2Lp..."
}

Errors

HTTP	error	Cause	Fix
400	`invalid_request`	A parameter is missing or malformed: no PKCE, PKCE with plain, a bad max_age, prompt=none combined with another prompt, or a token request that is not form encoded.	Send every required parameter once, PKCE with S256, and form-encode the token request.
401	`invalid_client`	Your app could not be authenticated: a wrong or expired secret, a revoked or expired certificate, a bad client_assertion (aud must be the token endpoint, exp at most ten minutes ahead, jti new), a public app sending a secret, or the app is suspended.	Check the credential on the app's Credentials page and its expiry. Rotate without downtime: add a new one, deploy, then revoke the old.
400	`invalid_grant`	The code or refresh token cannot be used: the code expired (60 seconds) or was used, it was issued to another client, the redirect_uri or code_verifier does not match, a refresh token was used twice, access was withdrawn, or the tester was removed.	Start the sign-in again. Swap each code once, straight away, with the same redirect_uri and the verifier you kept.
429	`rate_limited`	Over your quota for this bucket, this minute or this day.	Wait the Retry-After seconds. Requests over the limit still count, so a retry loop keeps you over it.

Good to know

Refresh tokens rotate. Keep only the newest, and send one refresh at a time for a person.
A refresh token used twice ends its whole line, because one of the two uses was not yours.
A refresh token expires after 90 days without use, and every token of a line expires one year after the sign-in it began with, however often it is used.

Security

Store refresh tokens encrypted at rest, and never send them to a browser.

Ask Atlas

AI assistant

Ask anything about Sign in with Atheron, the API or the portal. You get an answer from our docs, with links to the pages it used.