> ## 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.

# Quickstart

> Authenticate with the Health API, create a user, and make your first request.

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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
curl -sS "$BASE_URL/users?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## What to do next

<CardGroup cols={2}>
  <Card title="Understand auth" icon="shield-check" href="/authentication">
    Learn how project auth endpoints map to the canonical `/oauth/token` endpoint.
  </Card>

  <Card title="Map resource families" icon="database" href="/resources-and-pagination">
    See how users, daily records, summaries, facts, and meals fit together.
  </Card>

  <Card title="Configure webhooks" icon="webhook" href="/webhooks">
    Receive signed outbound events when ONVY data changes.
  </Card>

  <Card title="Browse endpoints" icon="terminal" href="/api-reference/introduction">
    Use the OpenAPI reference for route-by-route schemas and examples.
  </Card>
</CardGroup>

<Tip>
  `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`.
</Tip>