---
schema: agents-md/1.0
site_root: https://dev.1health.io/api/
route: /authentication
site_path: /authentication/agents.md
kind: endpoints
api_version: n/a
parent: /agents.md
source_version: staging-20260814 (app-observed routes; OpenAPI via 1H docs MCP; no pinned spec SHA)
generated_at: 2026-08-14T03:30:00Z
---

# Authentication Quickstart

Hand-authored per NG-8612 §5.4, derived from the documented endpoints and the verified implementations in five production applications.

## The three observed integration archetypes

**1. Session-token template app (human users).** The platform portal launches your app at `/auth?lpl=<base64>` with an AES-256-GCM-encrypted launch payload. Server-side: derive the key from your per-environment shared secret (HKDF-SHA256), decrypt the payload, HMAC-SHA256-sign the one-time code, then exchange it:

```bash
curl -X POST "https://demo.1health.io/api/v2/public/external-application/auth/oauth2/user/token" \
  -H "Content-Type: application/json" \
  -d '{"signature": "<hmac-of-one-time-code>", "securityCode": "<one-time-code>"}'
```

The response carries access + refresh tokens. Immediately call `GET /v2/tenant` to capture the organization context. All subsequent calls send `Authorization: Bearer <token>`. On 401, refresh at the **unversioned** root:

```bash
curl -X POST "https://demo.1health.io/auth/oauth2/token" \
  -d 'grant_type=refresh_token&client_id=public-client&refresh_token=$ONEHEALTH_REFRESH_TOKEN'
```

…and retry the original request once. Log out via `POST /auth/user/logout`.

**2. API-key backend caller (services, pipelines).** Mint a long-lived key scoped to access-control roles: resolve the role via `GET /v2/access-control/role/all`, then `POST /v2/token` with `acRoleIds`. The key value is returned once and can never be read back — store it as an environment secret. Use it for server-to-server ingestion and automation.

**3. SSO-only.** Run archetype 1's handshake purely to identify the user (one `GET /v2/user/myself` for the email), map them to your own account system, and never call the platform again.

## Tenancy semantics

A user can belong to multiple tenants (organizations). `GET /v2/user/myself` returns the active tenant and all memberships; `GET /v2/user/switch-tenant/{tenantId}?revokeToken=false` switches context (then refresh to mint an org-scoped token). Environments are fully separate: demo/sandbox (`https://demo.1health.io`) and production hosts have independent credentials, tokens, and data; production PHI access is gated on BAA acceptance (`/v2/agreement/...`).

## Navigation

Parent: https://dev.1health.io/api/agents.md · Site guide: https://dev.1health.io/api/agents.md