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

User Authorization

The application redirects the user to the authorization endpoint.

Authorization Code

Upon user consent, the application receives an authorization code.

Token Exchange

The application exchanges the authorization code for an access token.

Access Resource

The access token is used to access protected resources.

Endpoints

Authorization Endpoint

URL:/authorize

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

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)

API Endpoints for Resource Data

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

Get Metrics Data

URL:/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:/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 /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 /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 /api/partners/v1/user_data/metrics?date=2024-10-14
Authorization: Bearer ACCESS_TOKEN

GET /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 /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

Client ID

Redirect URI

Scope

State (Optional)

RESPONSE

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

Need to access these docs without logging in? View public OAuth documentation →

API Terms