Refresh an access token

Method	Path
POST	/auth/refresh-token

Authentication · Account routes

Exchanges a refresh token for a new access token and a new refresh token. Call it before the access token expires to keep a session alive.

note

This is an account-level route. It has no /auth/tenant/ variant. Use the refreshToken that a tenant sign-in or registration returned.

Auth: None. The refresh token in the body is the credential. Scope: The session the refresh token belongs to.

Request

Body

Name	Type	Required	Description
refresh_token	string	Yes	The refresh token of the session. At least 1 character. The name is in snake case.

Behaviour

• The answer holds access_token, refresh_token and expires_in, with snake case names. Sign-in answers use accessToken and refreshToken.
• Store the new refresh_token and use it for the next refresh.
• The access token is valid for one hour. expires_in is in seconds.
• A refresh token that the FHIR server rejects gives 400 with the FHIR server's description in message.
• A session of a patient whose project turned PATIENT_LOGIN_ENABLED off, or of a practitioner whose project turned PRACTITIONER_LOGIN_ENABLED off, gives 403 with Login is not enabled for this project. That ends the session: the refresh token is used up, and signing in again is refused while login is off.
• A practitioner who is a project admin is not refused, so a signed-in admin can still turn login back on. They cannot sign in again while it is off.
• The route is rate limited to 600 requests per minute for each caller. Over the limit the answer is 429, which can sign a user out, so refresh once per token lifetime and not in a loop.

Example

curl -X POST 'https://api.sandbox.ovok.com/auth/refresh-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "refresh_token": "<refresh token from sign-in>"
  }'

Successful response

201 — A new token pair.

{
  "access_token": "<new access token>",
  "refresh_token": "<new refresh token>",
  "expires_in": 3600
}

Field	Type	Description
access_token	string	Bearer access token. Valid for one hour.
refresh_token	string	The refresh token to use next.
expires_in	integer	Lifetime of the access token, in seconds.

Errors

Status	Meaning
400	The refresh token is unknown, expired or revoked, or the token could not be refreshed. The message carries the FHIR server's description when there is one.
403	Login is switched off for the project of a patient or of a non-admin practitioner. The session ends.
422	refresh_token is missing or empty.
429	More than 600 requests in a minute from the same caller.