Skip to main content
This quickstart uses the server convenience auth endpoint because it is the shortest path for backend and BFF integrations.

​
Prerequisites

  • An ONVY project_id
  • A confidential OAuth client with client_id and client_secret
  • A base URL for the environment you are targeting:
    • https://production.api.onvy.health
    • https://staging.api.onvy.health
    • https://testing.api.onvy.health

​
Step 1: Get a bearer token

Call POST /v1/projects/{project_id}/auth/server with HTTP Basic auth: 
BASE_URL="https://staging.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
}

​
Step 2: 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 3: 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 when to use /auth/server, /auth/sdk, or 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 token expires, request a new one from /auth/server or /oauth/token.