OAuth 2.0 authorization for the Partner API - Authorization Code Grant plus Refresh Token flow across the profile, ring_data, and cgm_data scopes. Users consent from the Ultrahuman app; access tokens live ~1 day (86400s) and refresh tokens rotate on each exchange. Includes authorize, token, and revoke endpoints. Client ID/secret and a registered redirect URI are issued during partner onboarding.
openapi: 3.0.3
info:
title: Ultrahuman Partner (UltraSignal) API
description: >-
The Ultrahuman Partner API gives approved partners read access to
user-consented health metrics from the Ultrahuman Ring AIR / Ring Pro and,
for users with an active M1 patch, the Ultrahuman CGM. Access is secured with
OAuth 2.0 (Authorization Code Grant plus Refresh Token flow) across three
scopes: profile, ring_data, and cgm_data. Access is not self-serve - partners
apply to the developer program and are issued a Client ID, Client Secret, and
a registered redirect URI during onboarding; end users authorize data sharing
from the Ultrahuman app (Profile -> Settings -> Partner ID). Access tokens
expire in ~1 day (86400 seconds); refresh tokens rotate on each exchange.
IMPORTANT: This document is MODELED by API Evangelist from Ultrahuman's public
partner developer documentation. Endpoint paths, scopes, OAuth flows, query
parameters, and the documented metric families are drawn from the docs;
exact request/response schemas are approximations and should be verified
against the live developer portal. Ultrahuman also documents a personal-token
variant at GET /api/v1/partner/daily_metrics for a developer's own ring data.
version: '1.0'
contact:
name: Ultrahuman Partnerships
url: https://partnerships.ultrahuman.com/
x-endpointsModeled: true
servers:
- url: https://partner.ultrahuman.com
description: Ultrahuman Partner API
tags:
- name: OAuth
description: OAuth 2.0 authorization, token exchange, and revocation.
- name: Metrics
description: Ring and CGM daily metrics for consented users.
- name: User
description: Basic authorized-user profile information.
paths:
/authorize:
get:
operationId: authorize
tags:
- OAuth
summary: Authorization endpoint (Authorization Code Grant)
description: >-
Redirects the user to Ultrahuman to consent to the requested scopes.
On approval, Ultrahuman redirects back to the registered redirect_uri
with an authorization code.
parameters:
- name: response_type
in: query
required: true
schema:
type: string
enum: [code]
- name: client_id
in: query
required: true
schema:
type: string
- name: redirect_uri
in: query
required: true
schema:
type: string
format: uri
- name: scope
in: query
required: true
description: Space-delimited scopes - profile, ring_data, cgm_data.
schema:
type: string
example: profile ring_data cgm_data
- name: state
in: query
required: false
schema:
type: string
responses:
'302':
description: Redirect to redirect_uri with an authorization code (or an error).
/api/partners/oauth/token:
post:
operationId: token
tags:
- OAuth
summary: Token endpoint (code exchange and refresh)
description: >-
Exchanges an authorization code for an access token, or exchanges a
refresh token for a new access token. Perform token exchanges
server-side. Refresh tokens rotate on each exchange.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: A new access token (and rotated refresh token).
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/partners/oauth/revoke:
post:
operationId: revoke
tags:
- OAuth
summary: Revoke a token
description: Revokes an access or refresh token.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required: [token, client_id, client_secret]
properties:
token:
type: string
client_id:
type: string
client_secret:
type: string
responses:
'200':
description: Token revoked.
'400':
$ref: '#/components/responses/BadRequest'
/api/partners/v1/user_data/metrics:
get:
operationId: getUserMetrics
tags:
- Metrics
summary: Get a user's daily health metrics
description: >-
Returns consented daily metrics for the authorized user. Ring metrics
require the ring_data scope; glucose/CGM metrics require the cgm_data
scope and an active M1 patch. Query by a single date (YYYY-MM-DD) or by a
start_epoch/end_epoch window (max range 7 days). date and the epoch pair
are mutually exclusive.
security:
- bearerAuth: []
parameters:
- name: date
in: query
required: false
description: Target day in YYYY-MM-DD. Mutually exclusive with the epoch pair.
schema:
type: string
format: date
- name: start_epoch
in: query
required: false
description: Window start, epoch seconds. Use with end_epoch (max 7-day range).
schema:
type: integer
format: int64
- name: end_epoch
in: query
required: false
description: Window end, epoch seconds.
schema:
type: integer
format: int64
- name: email
in: query
required: false
description: Optional target user's email for authorized multi-user access.
schema:
type: string
format: email
responses:
'200':
description: The user's metrics for the requested period.
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/partners/v1/user_data/user_info:
get:
operationId: getUserInfo
tags:
- User
summary: Get the authorized user's basic profile
description: >-
Returns basic profile info (user ID, time zone, etc.) for the authorized
user. Requires the profile scope.
security:
- bearerAuth: []
responses:
'200':
description: Basic user profile.
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfo'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 access token in the Authorization header.
responses:
BadRequest:
description: Invalid parameters, or the epoch window exceeded the 7-day limit.
Unauthorized:
description: Missing, invalid, or expired access token.
NotFound:
description: User not found, or the partner lacks permission for the requested data.
schemas:
TokenRequest:
type: object
required: [grant_type, client_id, client_secret]
properties:
grant_type:
type: string
enum: [authorization_code, refresh_token]
client_id:
type: string
client_secret:
type: string
code:
type: string
description: Required for grant_type=authorization_code.
redirect_uri:
type: string
format: uri
refresh_token:
type: string
description: Required for grant_type=refresh_token.
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 86400
refresh_token:
type: string
scope:
type: string
created_at:
type: integer
format: int64
UserInfo:
type: object
properties:
id:
type: string
timezone:
type: string
example: Asia/Kolkata
MetricsResponse:
type: object
description: >-
Modeled envelope of daily metrics. The docs describe roughly 40+ metric
fields spanning cardiovascular, sleep, glucose, activity/recovery, and
temperature families; representative fields are shown here.
properties:
date:
type: string
format: date
cardiovascular:
type: object
properties:
heart_rate:
type: number
hrv_rmssd:
type: number
night_resting_heart_rate:
type: number
sleep_hrv:
type: number
spo2:
type: number
sleep:
type: object
properties:
total_duration_minutes:
type: number
efficiency:
type: number
rem_minutes:
type: number
deep_minutes:
type: number
light_minutes:
type: number
sleep_score:
type: number
temperature_deviation:
type: number
activity_recovery:
type: object
properties:
steps:
type: integer
active_minutes:
type: number
movement_index:
type: number
recovery_index:
type: number
recovery_score:
type: number
metabolic_score:
type: number
vo2_max:
type: number
temperature:
type: object
properties:
skin_temperature_celsius:
type: number
avg_body_temperature_sleep:
type: number
glucose:
type: object
description: Present only with the cgm_data scope and an active M1 patch.
properties:
readings:
type: array
items:
type: object
properties:
epoch:
type: integer
format: int64
value_mgdl:
type: number
average_mgdl:
type: number
variability:
type: number
estimated_hba1c:
type: number
time_in_target_percent:
type: number