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.
If you are using an existing OAuth2 library, you may need to configure the following URLs.
https://cloud.ouraring.com/oauth/authorize
https://api.ouraring.com/oauth/token
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
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 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
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. |
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.
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
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. |
scope | 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 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
You can request access to 3 different scopes of user's data:
email
Email address of the userpersonal
Personal information (gender, age, height, weight)
daily
Daily summaries of sleep, activity and readinessWhen 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.
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:
GET /v1/userinfo HTTP/1.1 Host: api.ouraring.com Authorization: Bearer PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA
access_token
parameter to
the API call:https://api.ouraring.com/v1/userinfo?access_token=PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA
For features of OAuth2 not described in this document (refresh tokens, error situations, etc.), see the documentation on Oauth.net and RFC 6749.