Quickstart

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 type	Endpoint	When to use it
Backend or BFF	`POST /v1/projects/{project_id}/auth/server`	Your server needs an access token for machine-to-machine API calls.
Mobile or web app	`POST /v1/projects/{project_id}/auth/sdk`	You already have a user token from your identity provider and want an ONVY user token.
Direct OAuth integration	`POST /oauth/token`	You 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.

Overview

Core concepts

Prerequisites

Choose your authentication path

Backend or BFF authentication

Mobile or web authentication

Canonical OAuth endpoint

Step 1: Create a user

Step 2: Read data back

What to do next

Understand auth

Map resource families

Configure webhooks

Browse endpoints

​Prerequisites

​Choose your authentication path

​Backend or BFF authentication

​Mobile or web authentication

​Canonical OAuth endpoint

​Step 1: Create a user

​Step 2: Read data back

​What to do next

Understand auth

Map resource families

Configure webhooks

Browse endpoints

Prerequisites

Choose your authentication path

Backend or BFF authentication

Mobile or web authentication

Canonical OAuth endpoint

Step 1: Create a user

Step 2: Read data back

What to do next