API Documentation

OAuth2 Authentication

The Oura Cloud API uses the industry-standard OAuth2 protocol for authentication. In most cases you don't need implement the OAuth2 protocol yourself – instead, you should use an open source OAuth2 client library for your programming language or platform.

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

ParameterRequired?Description
response_type Required Value must be code
client_id Required The client ID you received after registering your application. You can see the client ID on the application's page under your Oura account.
redirect_uri Optional The URL in your app where users will be sent after authorization (see below). This value needs to be URL-encoded. 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 echoed back as a parameter in the redirect URL after succesful or unsuccesful authorization. This is typically used to identify the client application user or session that the authorization will be tied to. It should also contain an unguessable 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 this paramter is not given, the user will be prompted to give access to 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 https://redirect_url?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.)

If 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, together with the state parameter, if provided, for example: https://example.com/callback?error=access_denied&state=3PgHyjNECEu5YgTQP33NC5tZJ0onm2

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

ParameterRequired?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 The client ID you received after registering your application. You can find the client ID on the application's page under your Oura account.
client_secret Required if not using Basic Authorization The client secret you received after registering your application. You can find the client secret on the application's page under your Oura account.

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.

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

PropertyDescription
token_type "bearer"
access_token Alphanumerical string, a new access token that can be used to access the user's data through Oura API.
expires_in Number of seconds that the access token is valid for.
refresh_token Alphanumerical string, a refresh token that can be used to acquire a new access token after this access token expires. Read the OAuth documentation for more information on how to use it.

The Client-Side Only Flow

Note that the client-side only flow does not support refresh tokens. Once a token expires (usually after 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

ParameterRequired?Description
response_type Required Value must be token
client_id Required The client ID you received after registering your application. You can find the client ID on the application's page under your Oura account.
redirect_url Optional The URL in your app where users will be sent after authorization (see below). This value needs to be URL-encoded. 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 echoed back as a parameter in the fragment part of the redirect URL after succesful or unsuccesful authorization. This is typically used to identify the client application user or session that the authorization will be tied to. It should also contain an unguessable 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:

PropertyDescription
token_type "bearer"
access_token Alphanumerical string, a new access token that can be used to access the user's data through Oura API.
expires_in Number of seconds that the access token is valid for.
scopes Space-separated list of scopes that the access token is valid for. Note that this may be a subset of the requested scopes, in case the user chose not to give access to some of the requested scopes.
state The state parameter, echoed back as-is, if one was included in the call.

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 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 encoded in the fragment, together with the state parameter, if provided. For example: https://example.com/callback#error=access_denied&state=MZJMwJIqPLdQ3I69z5zIFNuD99YJcm


Scopes

You can request access to 3 different scopes of user's 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 (refresh tokens, error situations, etc.), see the documentation on Oauth.net and RFC 6749.