# Authentication API

See the 'Authentication' for description of this API


Version: 2.0
License: BSD-2-Clause

## Servers

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
```

## Security

## Download OpenAPI description

[Authentication API](https://dev-docs.tidepool.org/_bundle/reference/auth.v2.yaml)

## 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:

| Realm       | Server      |
| ----------- | ----------- |
| dev1        | Development |
| qa1         | QA          |
| qa2         | QA          |
| qa3         | QA          |
| qa4         | QA          |
| qa5         | QA          |
| integration | External    |
| tidepool    | Production  |


### Obtain Token

 - [POST /realms/{realm}/protocol/openid-connect/token](https://dev-docs.tidepool.org/reference/auth.v2/authentication/obtaintoken.md): 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

### Authorize

 - [GET /realms/{realm}/protocol/openid-connect/auth](https://dev-docs.tidepool.org/reference/auth.v2/authentication/authorize.md): 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.