Skip to content
Tidepool API/Authentication API/Authentication

Authentication API (2.0)

See the 'Authentication' for description of this API

Download OpenAPI description
auth.v2.json
auth.v2.yaml
Overview
URL

https://support.tidepool.org/

API Support

support@tidepool.org

License

BSD-2-Clause

Terms of Service

Languages
Servers
Mock server

https://tidepool.redocly.app/_mock/reference/auth.v2/

integration

https://external.integration.tidepool.org/

production

https://api.tidepool.org/

dev1

https://dev1.dev.tidepool.org/

qa1

https://qa1.development.tidepool.org/

qa2

https://qa2.development.tidepool.org/

qa3

https://qa2.development.tidepool.org/

qa4

https://qa2.development.tidepool.org/

qa5

https://qa2.development.tidepool.org/

Authentication

An OpenID Connect and OAuth2 compliant authentication API.

The authentication endpoints have a required realm realm parameter. The following is the list of all available realms and the servers they are available on:

RealmServer
dev1Development
qa1QA
qa2QA
qa3QA
qa4QA
qa5QA
integrationExternal
tidepoolProduction
Operations

Obtain Token

Request

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)

client_id=cgm-monitor
client_secret=c50e6502-131c-47f0-b439-a43acb3b83d0
grant_type=client_credentials

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 /token endpoint. This functionality is enabled only for trusted partners.

client_id=cgm-monitor
client_secret=c50e6502-131c-47f0-b439-a43acb3b83d0
grant_type=password
password=qwertyuiop1234
username=user@example.com

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.

client_id=cgm-monitor
client_secret=c50e6502-131c-47f0-b439-a43acb3b83d0
grant_type=refresh_token
refresh_token=eyJhbGciOiJ...

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 grant_type to be set to urn:ietf:params:oauth:grant-type:token-exchange.

The email address of the newly registered user will be obtained from the subject_token parameter. If an account with a duplicate email already exists the endpoint will return an error with "error_description": "User already exists" 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 kc_idp_hint 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.

client_id=cgm-monitor
client_secret=c50e6502-131c-47f0-b439-a43acb3b83d0
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
requested_token_type=urn:ietf:params:oauth:token-type:access_token
subject_issuer=acme-clinic
subject_token=eyJhbGciOiJ...
subject_token_type=urn:ietf:params:oauth:token-type:access_token
Path
realmstringrequired

The authentication realm.

Enum"dev1""qa1""qa2""qa3""qa4""qa5""integration""tidepool"
Bodyapplication/x-www-form-urlencoded
codestring

An authorization code obtained from authorization flow. Required if grant_type is authorization_code.

code_verifierstring
grant_typestringrequired

The mechanism used for authorizing requests for obtaining tokens.

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

Enum"authorization_code""refresh_token""password""urn:ietf:params:oauth:grant-type:token-exchange"
Example: "urn:ietf:params:oauth:grant-type:token-exchange"
client_idstringrequired

The client ID

Example: "cgm-monitor"
client_secretstring

The client secret if the client is confidential or it was issued credentials.

Example: "c50e6502-131c-47f0-b439-a43acb3b83d0"
subject_tokenstring

The subject token used in the token exchange flow. REQUIRED when grant_type is urn:ietf:params:oauth:grant-type:token-exchange

Example: "eyJhbGciOiJ..."
subject_token_typestring

The type of the subject token.

If the type is urn:ietf:params:oauth:token-type:access_token you must specify the subject_issuer parameter and it must be the alias of the configured identity provider. If the type is urn:ietf:params:oauth:token-type:jwt, 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"
Example: "urn:ietf:params:oauth:token-type:access_token"
requested_token_typestring

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"
Example: "urn:ietf:params:oauth:token-type:refresh_token"
subject_issuerstring

The issuer of subject_token. It must be a registered identity provider. REQUIRED when subject_token_type is urn:ietf:params:oauth:token-type:access_token

Example: "acme-clinic"
usernamestring

The username of the end-user being authenticated when using the Password Credentials Grant

Example: "user@example.com"
passwordstring

The password of the end-user being authenticated when using the Password Credentials Grant

Example: "qwertyuiop1234"
curl -i -X POST \
  'https://tidepool.redocly.app/_mock/reference/auth.v2/realms/{realm}/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=cgm-monitor \
  -d client_secret=c50e6502-131c-47f0-b439-a43acb3b83d0 \
  -d grant_type=password \
  -d password=qwertyuiop1234 \
  -d username=user@example.com

Responses

OK

Bodyapplication/json
access_tokenstring

A short-lived access token for the currently authenticated subject.

Example: "ODBkOTY5NWUtN2I0Mi00ODQwLWI0ZTEtZDdmYjcwMjhhZWIyCg=="
expires_ininteger

The number of seconds the access token expires in

Example: 60
refresh_expires_ininteger

The number of seconds the refresh token expires in

Example: 7200
refresh_tokenstring

The refresh token that can be used to obtain a new access token for the subject after the previous one had expired.

Example: "ZWM0MGZjYzctMWExZC00NmM4LTlhOTgtOTVjOTYyNGFiNWZhCg=="
scopestring

The authorized scopes

Example: "openid email"
id_tokenstring

An ID token associated with the authenticated session. The value will only be returned if the openid scope was requested.

Example: "MDY3YzJmMjctOTliMi00N2ZjLWFkMGUtMzY3NzliMmJiNGI1Cg=="
Response
application/json
{
  "access_token": "ODBkOTY5NWUtN2I0Mi00ODQwLWI0ZTEtZDdmYjcwMjhhZWIyCg==",
  "expires_in": 60,
  "refresh_expires_in": 7200,
  "refresh_token": "ZWM0MGZjYzctMWExZC00NmM4LTlhOTgtOTVjOTYyNGFiNWZhCg==",
  "scope": "openid email",
  "id_token": "MDY3YzJmMjctOTliMi00N2ZjLWFkMGUtMzY3NzliMmJiNGI1Cg=="
}

Authorize

Request

The starting point for browser-based OpenID Connect flows. This endpoint authenticates the user and returns an authorization grant or an access token to callback endpoint at the specified redirect_uri.

Path
realmstringrequired

The authentication realm.

Enum"dev1""qa1""qa2""qa3""qa4""qa5""integration""tidepool"
Query
client_idstringrequired

Client Identifier valid at the Authorization Server

scopeArray of stringsrequired

OpenID Connect requests MUST contain the openid scope value

Items Enum"openid""email"
response_typestringrequired

Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value is code.

Value"code"
redirect_uristringrequired

Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider

login_hintstring

Hint to the Authorization Server about the login identifier the End-User might use to log in

kc_idp_hintstring

OIDC applications can bypass the login page by hinting at the identity provider they want to use

promptstring

Specifies whether the Authorization Server prompts the End-User for reauthentication and consent

Enum"none""login"
curl -i -X GET \
  'https://tidepool.redocly.app/_mock/reference/auth.v2/realms/{realm}/protocol/openid-connect/auth?client_id=string&scope=openid&response_type=code&redirect_uri=string&login_hint=string&kc_idp_hint=string&prompt=none'

Responses

Both successful and error responses result in a browser redirect to the callback endpoint