Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.onvy.health/llms.txt

Use this file to discover all available pages before exploring further.

This page shows how to authenticate against the Health API and make your first request. It continues with the server flow because that is the fastest way to verify your integration.

​
Prerequisites

  • An ONVY project_id
  • A confidential OAuth client with client_id and client_secret for server-to-server traffic
  • If you are authenticating end users, an upstream OIDC token or refresh token from your identity provider
  • The API base URL: https://api.onvy.health

​
Choose your authentication path

Integration typeEndpointWhen to use it
Backend or BFFPOST /v1/projects/{project_id}/auth/serverYour server needs an access token for machine-to-machine API calls.
Mobile or web appPOST /v1/projects/{project_id}/auth/sdkYou already have a user token from your identity provider and want an ONVY user token.
Direct OAuth integrationPOST /oauth/tokenYou want to call the canonical OAuth endpoint directly.
All protected routes expect the resulting token in the Authorization: Bearer <access_token> header.

​
Backend or BFF authentication

Use POST /v1/projects/{project_id}/auth/server with HTTP Basic auth. This endpoint exchanges your confidential client credentials for an ONVY bearer token. 
BASE_URL="https://api.onvy.health"
PROJECT_ID="proj_your_project"
CLIENT_ID="server"
CLIENT_SECRET="your_client_secret"

curl -sS -X POST "$BASE_URL/v1/projects/$PROJECT_ID/auth/server" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"scope":"users:create users:read"}'
Example response: 
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900
}

​
Mobile or web authentication

Use POST /v1/projects/{project_id}/auth/sdk when you authenticate users with your own identity provider and want an ONVY user token in return. Exchange an upstream OIDC token: 
curl -sS -X POST "$BASE_URL/v1/projects/$PROJECT_ID/auth/sdk" \
  -H "Content-Type: application/json" \
  -d '{
    "grant": "exchange",
    "token": "'"$ID_TOKEN"'",
    "client_id": "sdk"
  }'
Refresh an ONVY refresh token: 
curl -sS -X POST "$BASE_URL/v1/projects/$PROJECT_ID/auth/sdk" \
  -H "Content-Type: application/json" \
  -d '{
    "grant": "refresh",
    "token": "'"$REFRESH_TOKEN"'",
    "client_id": "sdk"
  }'

​
Canonical OAuth endpoint

If you need direct grant-level control, call POST /oauth/token with application/x-www-form-urlencoded parameters. The /authentication page shows the supported grant shapes and examples.

​
Step 1: Create a user

User IDs are customer-supplied and unique within a project. 
ACCESS_TOKEN="eyJ..."

curl -sS -X POST "$BASE_URL/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_123",
    "firstname": "Avery",
    "lastname": "Smith",
    "language": "en",
    "measurement_unit": "metric",
    "tz_offset": 3600
  }'

​
Step 2: Read data back

Confirm the token works by listing users: 
curl -sS "$BASE_URL/users?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​
What to do next

Understand auth

Learn how project auth endpoints map to the canonical /oauth/token endpoint.

Map resource families

See how users, daily records, summaries, facts, and meals fit together.

Configure webhooks

Receive signed outbound events when ONVY data changes.

Browse endpoints

Use the OpenAPI reference for route-by-route schemas and examples.
client_credentials tokens do not return a refresh token. When a server token expires, request a new one from /v1/projects/{project_id}/auth/server or /oauth/token.