Authentication

Two kinds of API keys exist, and both are sent the same way:

Credential	Shape	Acts as
Personal API key	`omnara_pat_v1_…`	You — your roles, your project access
Org API key	`omnara_org_v1_…`	The org itself — a service account for integrations and automations

(Connected machines authenticate with their own daemon tokens, minted in the connect flow and valid only on daemon routes.) Treat bearer tokens as opaque: store and send the complete value without parsing its prefix, version, or checksum.

Using an API key

Send either key as a bearer token. This example uses a personal key because /me is a user-only endpoint:

curl https://api.omnara.com/v1/me \
  -H "Authorization: Bearer $OMNARA_TOKEN"

{
  "user": { "id": "usr_ehcyd5n6a2bfgik7mv4qtrwz3j", "email": "you@example.com", "display_name": "You" },
  "orgs": [ { "id": "org_k7mv4qtrwz3jehcyd5n6a2bfgi", "name": "Acme", "role": "owner", "created_at": "2026-08-01T17:02:11Z" } ]
}

A personal API key authenticates as you and carries exactly your roles and project access — no more, no less. There are no separate API scopes to configure; what you can do in the dashboard, your token can do through the API. For service integrations, use an org API key instead, so access doesn’t hinge on one person’s account. A missing or invalid token returns 401 with code unauthorized. A valid token used on something your roles don’t permit returns 403 — or 404 if you can’t even see the resource. Details in Errors.

Creating personal keys

Tokens are minted where a human can approve them — creating one is deliberately not possible with another API key:

Dashboard — go to API Tokens in the sidebar and click New token. The full token is shown once.
Device login — for CLIs and dev tools, below.

Only a hash is stored server-side, so save the token when it is shown.

Org API keys for services

Services shouldn’t run as a person — when that person leaves or their access changes, the integration breaks. An org API key is its own principal: it holds an org role (admin or member) and per-project roles, granted exactly like a member’s. Create one in the dashboard: open API Tokens, switch to the Organization tab, and under Organization API tokens click New token. Pick a name and org role; the omnara_org_v1_… token is shown once. Then grant the key project roles from its detail panel — a member-role key sees nothing until you do, same as a human member. Key management stays human-gated: creating, renaming, changing roles, and revoking all require a dashboard session, so one API key can never mint or escalate another. Listing and reading key metadata work with regular API auth (List org API keys). Revocation is permanent and drops the key’s org and project roles (Revoke). The device flow gets a token onto a machine where pasting secrets is awkward. It’s three steps: request a code, have the user approve it in a browser, poll for the token. These routes live under /api/auth (not /api/v1) and the first two need no authentication. 1. Start the flow:

curl https://app.omnara.com/api/auth/device/code \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "acme-cli", "token_name": "laptop of dana" }'

client_name identifies the requesting client on the approval screen, while token_name names the resulting personal access token. When provided, both use the 64-character resource-name policy. Omitting either field or sending an empty value uses Device or Device login, respectively.

{
  "device_code": "b62d4cb3…",
  "user_code": "GLPM-XKCD",
  "verification_uri": "https://app.omnara.com/device",
  "verification_uri_complete": "https://app.omnara.com/device?user_code=GLPM-XKCD",
  "expires_in": 900,
  "interval": 5
}

2. Send the user to approve. Open verification_uri_complete (or show user_code and point them at verification_uri). They sign in and approve — or deny — on the dashboard’s Approve device login page. 3. Poll for the token every interval seconds with the private device_code:

curl https://app.omnara.com/api/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "b62d4cb3…" }'

While the user hasn’t decided, you get 202:

{ "error": "authorization_pending", "interval": 5 }

(slow_down means you’re polling too fast — back off to the returned interval.) On approval, 200 delivers a normal API key:

{ "access_token": "omnara_pat_v1_…", "token_type": "Bearer" }

A denied or expired flow returns 400 with "access_denied" or "expired_token". The resulting token is a regular personal access token for the approving user, named after token_name — it appears in their token list like any other.

Managing tokens

The API Tokens page — or List personal access tokens — shows your tokens with creation and last-used times, metadata only: the secret is never shown again. last_used_at tells you which tokens are actually alive; prune the rest, and revoke immediately if a token leaks — revocation is permanent.

API reference

Endpoints

Authentication

Using an API key

Creating personal keys

Org API keys for services

Managing tokens

​Using an API key

​Creating personal keys

​Org API keys for services

​Device login for CLIs

​Managing tokens

Using an API key

Creating personal keys

Org API keys for services

Device login for CLIs

Managing tokens