# Obtain Token

Obtain an access, id and refresh token(s) by using an authorization code, client credentials or a valid refresh token .

If the token request is valid and authorized, the authorization server issues an access token and optional refresh token. If the request client authentication failed or is invalid, the authorization server returns an error response.

### Client Credentials Grant (Service Account authentication)

Use this method of authentication if you're accessing Tidepool API's from a non-browser environment (e.g. backend-to-backend connection)



### Password Credentials Grant

This capability is not available to the general public - Tidepool's recommendation is to use the "Authorization Code" flow, which will authenticate the user in a browser session. When this is not feasible (e.g. for programmatic access) it is possible to use the "Password Credentials" grant which allows obtaining access and refresh tokens by providing a valid username and password to the  endpoint. This functionality is enabled only for trusted partners.



### Refresh Token

Access tokens are short-lived and are valid for up to 10 minutes. You should use the refresh token obtained previously and exchange it for a new access and refresh token pair. Always use the most recently obtained refresh token when making the request. 



### Token Exchange Flow

Trusted partners can use the token exchange flow to provision new users in Tidepool using an access or an ID token. The token exchange flow requires  to be set to . 

The email address of the newly registered user will be obtained from the  parameter. If an account with a duplicate email already exists the endpoint will return an error with  in the response body.

An already existing user can be linked to the external identity provider by going through the standard authorization code flow by redirecting the user in a browser to the authorization endpoint. The external identity provider can be pre-selected by setting  query parameter of the authorization request.

A fresh access and/or refresh token can be issued for users which have an existing link to the external identity provider or were provisioned by this flow.



Endpoint: POST /realms/{realm}/protocol/openid-connect/token
Version: 2.0

## Path parameters:

  - `realm` (string, required)
    The authentication realm.
    Enum: "dev1", "qa1", "qa2", "qa3", "qa4", "qa5", "integration", "tidepool"

## Request fields (application/x-www-form-urlencoded):

  - `code` (string)
    An authorization code obtained from authorization flow. Required if  is .

  - `code_verifier` (string)

  - `grant_type` (string, required)
    The mechanism used for authorizing requests for obtaining tokens.

 - used in the authorization code flow
 - used for refreshing expired access tokens with an active refresh token
 - used in the token exchange flow
    Enum: "authorization_code", "refresh_token", "password", "urn:ietf:params:oauth:grant-type:token-exchange"

  - `client_id` (string, required)
    The client ID
    Example: "cgm-monitor"

  - `client_secret` (string)
    The client secret if the client is confidential or it was issued credentials.
    Example: "c50e6502-131c-47f0-b439-a43acb3b83d0"

  - `subject_token` (string)
    The subject token used in the token exchange flow.  when  is
    Example: "eyJhbGciOiJ..."

  - `subject_token_type` (string)
    The type of the subject token.

If the type is  you must specify the  parameter and it must be the alias of the configured identity provider. If the type is , the provider will be matched via the issuer claim within the JWT which must be the alias of the provider, or a registered issuer within the providers configuration.

For validation, if the token is an access token, the provider’s user info service will be invoked to validate the token. A successful call will mean that the access token is valid. If the subject token is a JWT and if the provider has signature validation enabled, that will be attempted, otherwise, it will default to also invoking on the user info service to validate the token.
    Enum: "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:jwt"

  - `requested_token_type` (string)
    The type of token that will be issued in the token exhange flow.
    Enum: "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:refresh_token"

  - `subject_issuer` (string)
    The issuer of . It must be a registered identity provider.  when  is
    Example: "acme-clinic"

  - `username` (string)
    The username of the end-user being authenticated when using the Password Credentials Grant
    Example: "user@example.com"

  - `password` (string)
    The password of the end-user being authenticated when using the Password Credentials Grant
    Example: "qwertyuiop1234"

## Response 200 fields (application/json):

  - `access_token` (string)
    A short-lived access token for the currently authenticated subject.
    Example: "ODBkOTY5NWUtN2I0Mi00ODQwLWI0ZTEtZDdmYjcwMjhhZWIyCg=="

  - `expires_in` (integer)
    The number of seconds the access token expires in
    Example: 60

  - `refresh_expires_in` (integer)
    The number of seconds the refresh token expires in
    Example: 7200

  - `refresh_token` (string)
    The refresh token that can be used to obtain a new access token for the subject after the previous one had expired.
    Example: "ZWM0MGZjYzctMWExZC00NmM4LTlhOTgtOTVjOTYyNGFiNWZhCg=="

  - `scope` (string)
    The authorized scopes
    Example: "openid email"

  - `id_token` (string)
    An ID token associated with the authenticated session. The value will only be returned if the  scope was requested.
    Example: "MDY3YzJmMjctOTliMi00N2ZjLWFkMGUtMzY3NzliMmJiNGI1Cg=="

## Response 400 fields (application/json):

  - `error` (string)
    The error identifier
    Example: "invalid_token"

  - `error_description` (string)
    Description of the error that occurred
    Example: "User already exists"