# 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://tidepool.redocly.app/_spec/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://tidepool.redocly.app/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)



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



### Authorize

 - [GET /realms/{realm}/protocol/openid-connect/auth](https://tidepool.redocly.app/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 .