API Documentation

Getting Started V2 API Authentication Error Handling

Authentication

The Oura Cloud API offers two methods for Authentication. Oura offers an industry standard OAuth2 protocol as well as Personal Access Tokens.

OAuth2 Authentication

Oura offers an industry standard OAuth2 protocol. 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.

If you intend to only pull your own personal data, Personal Access Tokens may fit your needs better.

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

Scopes

You can request access to 8 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
  • heartrate Time series heart rate for Gen 3 users
  • workout Summaries for auto-detected and user entered workouts
  • tag User entered tags
  • session Guided and unguided sessions in the Oura app
  • spo2Daily SpO2 Average recorded during sleep

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.

The Server-side Flow

i. Direct Users To Log Into 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

ii. Oura Redirects Back To Your Site

When the user grants access to your application, Oura will redirect them to your redirect URL with a code, scope and optional state query parameter. Note that the space-separated list of scopes may be different than the scopes that were requested. The redirect call format is:

GET redirect_uri?code=XXX&scope=SCOPES&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&scope=email%20personal&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2

(The code parameter will be different each time, of course.)

If The User Denies Access

If the user denies the request for authorization, the redirect will be to the same redirect URI, but with the parameter error=access_denied instead of the code parameter. Any supplied state parameter will be included as well. For example: https://example.com/callback?error=access_denied&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2

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

iv. Get 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.

i. Direct Users To Log Into 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

ii. 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.)

If The User Denies Access

If the user denies the request for authorization, the redirect will be to the same redirect URI, but with the parameter error=access_denied instead of the access_token parameter. Any supplied state parameter will be included as well. For example: https://example.com/callback?error=access_denied&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2

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 by including the access token in the Authorization header: 

GET /v2/usercollection/sleep HTTP/1.1
Host: api.ouraring.com
Authorization: Bearer PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA

Revoking The Access Token

When you need to revoke access for a specific token use the following API call format:

URL parameter: Replace client_id and access_token with the corresponding values the API call:
https://api.ouraring.com/oauth/revoke?access_token={access_token}

Further reading

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

Personal Access Tokens

Oura offers Personal Access Tokens for Authentication. Personal access tokens (PATs) may be used for retrieving your own personal data from the Oura Cloud API.

If you wish to build an integration allowing multiple Oura Users to share their data, using OAuth2 may fit your needs better.

Create A Personal Access Token

  1. Navigate to the Personal Access Tokens page
  2. In the upper-right corner of the page click the "Create A New Personal Access Token" Button
  3. Enter a unique note for the new Personal Access Token you are about to generate
    • This note is just a reminder for yourself about what the token is being used for
  4. Click "Create Personal Access Token" to submit the form and create your new Personal Access Token
  5. You should now have a new access token listed on the Personal Access Tokens page

Be sure to copy this new token as you will not be able to view the token once navigating away. Use the convenient "Copy" button to copy the token value into your clipboard.

Using A Personal Access Token

Once you have acquired a Personal Access Token, the token can be used to access the Oura API by including the Personal Access Token in the Authorization header: 

GET /v2/usercollection/sleep HTTP/1.1
Host: api.ouraring.com
Authorization: Bearer PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA

©2021 Ōura Health Oy. All Rights Reserved. ŌURA and OURA and Ō are trademarks of Ōura Health Oy and may not be used without permission.