Documentation

v1.0
Live

OAuth 2.0 Provider Documentation

Overview

This documentation provides the necessary details for third-party applications to integrate with our OAuth 2.0 provider. The provider supports the Authorization Code Grant flow and Refresh Token flow.

Supported Flows

  • • Authorization Code Grant Flow
  • • Refresh Token Flow
  • • Secure token-based authentication
  • • User consent and authorization

Authorization Code Grant Flow

The Authorization Code Grant flow is used for server-side applications. This flow allows applications to obtain an authorization code and exchange it for an access token.

Flow Steps

1

User Authorization

The application redirects the user to the authorization endpoint.

2

Authorization Code

Upon user consent, the application receives an authorization code.

3

Token Exchange

The application exchanges the authorization code for an access token.

4

Access Resource

The access token is used to access protected resources.

Endpoints

Authorization Endpoint

URL:https://auth.ultrahuman.com/authorise
Method:GET

Parameters:

response_type(string)required

Must be code

client_id(string)required

The client identifier issued during registration

redirect_uri(string)required

The URI to redirect back to after authorization

scope(string)optional

Space-separated list of requested scopes

state(string)optional

A value to maintain state between the request and callback

Token Endpoint

URL:https://partner.ultrahuman.com/api/partners/oauth/token
Method:POST

Parameters for fresh access tokens:

grant_type(string)required

Must be authorization_code

client_id(string)required

The client identifier issued during registration

client_secret(string)required

The client secret

code(string)required

The authorization code received from the authorization endpoint

redirect_uri(string)required

Must match the redirect URI used during authorization

Parameters for refreshing tokens:

grant_type(string)required

Must be refresh_token

client_id(string)required

The client identifier issued during registration

client_secret(string)required

The client secret

refresh_token(string)required

Refresh token here

Revoke Token Endpoint

URL:https://partner.ultrahuman.com/api/partners/oauth/revoke
Method:POST

Parameters for revoking tokens:

token(string)required

The token to be revoked

client_id(string)required

The client identifier issued during registration

client_secret(string)required

The client secret

Response:

• Success (200 OK): If the token is successfully revoked or if the token is already invalid (expired or not found)

• Error (400 Bad Request): If the request is malformed, missing parameters, or unauthorized

Access Tokens

Access tokens are required to access protected resources. They are issued after a successful token exchange and are valid for a week, post week they need to be refreshed.

Token Type:Bearer
Expiration:86400 seconds (1 day)
Refresh:Required after expiration

Scopes

Scopes define the level of access granted to the application. This scopes should be included in the params when requesting the access. Applications should request only the scopes they require.

You can give your app any scope below except cgm_data when you create it, and change them later from the OAuth applications page. cgm_data is granted on request. A member who already connected keeps the scopes they agreed to, so they must connect again to grant one you add. A scope you remove stops working at once.

profile

Grants read access to the user's basic info like ID, Time zone, etc. (required for /user_info API)

ring_data

Grants read access to user's ring metrics (required for ring data in /metrics API)

cgm_data

Grants read access to user's CGM metrics (required for cgm data in /metrics API). Granted on request.

ring_extended_data

Grants read access to extended daily ring metrics such as cardio age, stress score and calories burned (adds them to the /metrics API).

workout

Grants read access to the user's workouts (adds them to the /metrics API).

sleep_info

Grants read access to the bedtime and deep and REM sleep percentages for recent nights (required for the /sleep_info API).

API Endpoints for Resource Data

Access user data using these endpoints with a valid access token.

Get Metrics Data

URL:https://partner.ultrahuman.com/api/partners/v1/user_data/metrics
Method:GET

Headers:

Authorization(string)required

Bearer <ACCESS_TOKEN>

Parameters:

date(string)required

The date for which the data is requested

Get User Info

URL:https://partner.ultrahuman.com/api/partners/v1/user_data/user_info
Method:GET

Headers:

Authorization(string)required

Bearer <ACCESS_TOKEN>

Error Responses

In case of an error, the server responds with a JSON object containing:

error(string)

A string indicating the error type (e.g., invalid_request, unauthorized_client)

error_description(string)

A human-readable description of the error

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code."
}

Examples

Authorization Code Grant Flow

User Authorization Request:

GET https://auth.ultrahuman.com/authorise?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=ring_data%20cgm_data

Redirect to Callback:

After user consent, the application is redirected:

GET /callback?code=AUTHORIZATION_CODE&state=STATE

Token Exchange:

The application exchanges the authorization code for an access token:

POST https://partner.ultrahuman.com/api/partners/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Response:

A successful response returns the access token:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 86399,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "profile ring_data cgm_data",
  "created_at": 1731066548
}

Access Protected Resource:

Use the access token to access resources:

GET https://partner.ultrahuman.com/api/partners/v1/user_data/metrics?date=2024-10-14
Authorization: Bearer ACCESS_TOKEN

GET https://partner.ultrahuman.com/api/partners/v1/user_data/user_info
Authorization: Bearer ACCESS_TOKEN

Refresh Token Flow

Token Refresh Request:

To refresh the access token, the application uses the refresh token:

POST https://partner.ultrahuman.com/api/partners/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN

Response:

A successful response returns a new access token and refresh token, next time you refresh the tokens make sure to use the newly granted refresh token:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "profile ring_data cgm_data",
  "created_at": 1731066449
}

Code Sample

# Authorization Request
curl -X GET "https://auth.ultrahuman.com/authorise?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=ring_data%20cgm_data%20profile"

Try It Out

RESPONSE

Click Try It! to start a request and see the response here!

Want to access your personal tokens and create OAuth apps? Login to view authenticated documentation →

API Terms