OAuth2 Authentication

The Oura Cloud API uses the industry-standard OAuth2 protocol for authentication. In most cases, you should not implement the OAuth2 protocol yourself – instead, using a ready-made OAuth2 client library for your programming language or platform is recommended.

Authorization and access token URLs

If you are using an existing OAuth2 library, you may need to configure the following URLs.

• Authorize: https://cloud.ouraring.com/oauth/authorize
• Access Token URL: https://api.ouraring.com/oauth/token

---

The Server-side Flow

1. Direct users to log in to Oura and authorize your app: GET /oauth/authorize

Parameter	Required?	Description
response_type	Required	Value must be code
client_id	Required	Your developer application's client ID. You can find the client ID on the application's page, which is listed under My Applications.
redirect_uri	Optional	The URL in your app where users will be sent after authorization (see below). This value needs to be URL-encoded. The redirect URIs listed for your application act as a whitelist of allowed values, meaning this parameter must match one of the URIs exactly. If your application has been configured with exactly one redirect URI, this parameter can be left out and the configured redirect URI will be used. However, it is adivisable to always include the redirect URI parameter.
state	Optional	Arbitrary string that will be sent back to your service as a parameter in the redirect URL after a succesful or unsuccesful authorization. This is typically used to identify the user or session that the authorization will be tied to. It should also contain a random string to protect against cross-site request forgery attacks.
scope	Optional	Space-separated list of permissions (scopes) your application requests access to. See Scopes. If left blank, the application will request all available scopes.

Example authorization request: https://cloud.ouraring.com/oauth/authorize?response_type=code&client_id=E55QJ2DGMZUXK6TN&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=email+personal&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2

2. Oura redirects back to your site.

When the user grants access to your application, Oura will redirect them to your redirect URL. Redirect call format is:

GET redirect_uri?code=XXX&state=YYY

If the user authorizes the application, the example authorization request above will result in the following redirect: https://example.com/callback?code=TRUQR7C6PRIYDRXMCQLAMW4V5LFFZVFO&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2 (The code parameter will be different each time, of course.)

3. Exchange code for access token: POST /oauth/token

Parameter	Required?	Description
grant_type	Required	Value must be authorization_code
code	Required	The authorization code received in the previous step as the code parameter to the redirect URI.
redirect_uri	Optional	The exact same redirect URI that was included in the authorization request that provided the code. If no URI was given in the authorization request, then this parameter must also be left out of this request.
client_id	Required if not using Basic Authorization	Your developer application's client ID. You can find the client ID on the application's page, which is listed under My Applications.
client_secret	Required if not using Basic Authorization	Your developer application's client secret. You can find the client secret on the application's page, which is listed under My Applications.

Instead of providing client_id and client_secret as parameters, they can be given using the HTTP Basic Authorization, with client_id as username and client_secret as password.

The parameters must be passed in the request body, using the "application/x-www-form-urlencoded" format and UTF-8 encoding.

The reply to the request, provided that it is valid, is a JSON object with the following properties:

Property	Description
token_type	"bearer"
access_token	An alphanumerical string. This is a new access token that can be used to access the user's data through the Oura API.
expires_in	Number of seconds that the access token is valid for.
refresh_token	An alphanumerical string. A refresh token that can be used to acquire a new access token (and refresh token) after this access token expires. The refresh token is single-use, meaning it is invalidated after being used.

4. Get a new access token using the refresh token: POST /oauth/token

Parameter	Required?	Description
grant_type	Required	Value must be refresh_token
refresh_token	Required	The refresh_token received when exchanging a code or older refresh_token for an access token.
client_id	Required if not using Basic Authorization	Your developer application's client ID. You can find the client ID on the application's page, which is listed under My Applications.
client_secret	Required if not using Basic Authorization	Your developer application's client secret. You can find the client secret on the application's page, which is listed under My Applications.

Instead of providing client_id and client_secret as parameters, they can be given using the HTTP Basic Authorization, with client_id as username and client_secret as password.

The parameters must be passed in the request body, using the "application/x-www-form-urlencoded" format and UTF-8 encoding.

The reply to the request, provided that it is valid, is a JSON object with the following properties:

Property	Description
token_type	"bearer"
access_token	An alphanumerical string. This is a new access token that can be used to access the user's data through the Oura API.
expires_in	Number of seconds that the access token is valid for.
refresh_token	An alphanumerical string. A refresh token that can be used to acquire a new access token (and refresh token) after this access token expires. The refresh token is single-use, meaning it is invalidated after being used.

---

The Client-Side Only Flow

Note that the client-side only flow does not support refresh tokens. Once a token expires (currently set to 30 days), the user will need to re-authenticate your app.

1. Direct users to log in to Oura and authorize your app: GET /oauth/authorize

Parameter	Required?	Description
response_type	Required	Value must be token
client_id	Required	Your developer application's client ID. You can find the client ID on the application's page, which is listed under My Applications.
redirect_uri	Optional	The URL in your app where users will be sent after authorization (see below). This value needs to be URL-encoded. The redirect URIs listed for your application act as a whitelist of allowed values, meaning this parameter must match one of the URIs exactly. If your application has been configured with exactly one redirect URI, this parameter can be left out and the configured redirect URI will be used. However, it is adivisable to always include the redirect URI parameter.
state	Optional	Arbitrary string that will be sent back to your service as a parameter in the redirect URL after a succesful or unsuccesful authorization. This is typically used to identify the user or session that the authorization will be tied to. It should also contain a random string to protect against cross-site request forgery attacks.
scope	Optional	Space-separated list of permissions (scopes) your application requests access to. See Scopes. If left blank, the application will request all available scopes.

Example authorization request: https://cloud.ouraring.com/oauth/authorize?response_type=token&client_id=E55QJ2DGMZUXK6TN&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=email+personal&state=MZJMwJIqPLdQ3I69z5zIFNuD99YJcm

2. Oura redirects back to your site.

When the user grants access to your application, Oura will redirect them to your redirect URL. The following properties are included in the fragment part of the redirect URL, encoded using the "application/x-www-form-urlencoded" format:

Property	Description
token_type	"bearer"
access_token	An alphanumerical string. This is a new access token that can be used to access the user's data through the Oura API.
expires_in	Number of seconds that the access token is valid for.
scope	Space-separated list of scopes that the access token is valid for. Note that this may be a subset of the requested scopes if the user chose not to give access to some of the requested scopes.
state	The state parameter, returned back as-is, if it was included in the authorization request.

The example authorization request above will result in the following redirect if the user authorizes the application: https://example.com/callback#token_type=bearer&access_token=PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA&expires_in=2592000&scope=email+personal&state=MZJMwJIqPLdQ3I69z5zIFNuD99YJcm (The access_token will be different each time, of course.)

---

Scopes

You can request access to 3 different scopes of user data:

• email Email address of the user
• personal Personal information (gender, age, height, weight)
• daily Daily summaries of sleep, activity and readiness

When an Oura user authorizes access to your application, she can enable and disable scopes based on her preferences. Require only access to the scopes that your application needs. For example, if your application doesn't require the email address of the user, leave it out.

---

Using the access token

Once your application has acquired an access token using either of the authorization flows, the token can be used to access the Oura API. There are two ways of providing the access token:

1. HTTP header: Include the access token in the Authorization header like this:

   GET /v1/userinfo HTTP/1.1
   Host: api.ouraring.com
   Authorization: Bearer PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA
   

2. URL parameter: Add access_token parameter to the API call:
   https://api.ouraring.com/v1/userinfo?access_token=PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA

---

Further reading

For features of OAuth2 not described in this document, see the documentation on Oauth.net and RFC 6749.