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

Parameter	Required?	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.)

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

Property	Description
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

Parameter	Required?	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:

Property	Description
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.)

---

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.