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 — with All projects selected in the project switcher, open API Tokens 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: with All projects selected in the project switcher, 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). Omnara supports the OAuth 2.0 Device Authorization Grant. The returned access token is a regular Omnara personal access token. Start by discovering the endpoints for the Omnara installation:

curl https://app.omnara.com/.well-known/oauth-authorization-server

Use the endpoint URLs returned by this metadata rather than constructing them. 1. Start the flow:

curl https://app.omnara.com/api/auth/device/code \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=omnara-cli" \
  --data-urlencode "token_name=laptop of dana"

client_id must be omnara-cli; other public clients are not currently registered. token_name is an optional Omnara extension for naming the resulting PAT; it uses the 64-character resource-name policy and defaults to Device login.

{
  "device_code": "b62d4cb3…",
  "user_code": "A1B2C-D3E4F",
  "verification_uri": "https://app.omnara.com/device",
  "verification_uri_complete": "https://app.omnara.com/device?user_code=A1B2C-D3E4F",
  "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/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "device_code=b62d4cb3…" \
  --data-urlencode "client_id=omnara-cli"

While the user hasn’t decided, the token endpoint returns 400:

{ "error": "authorization_pending" }

Keep polling at the returned interval. After slow_down, add five seconds to the interval for this and later requests. On approval, 200 returns the PAT:

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

A denied or expired flow returns 400 with "access_denied" or "expired_token". The PAT does not expire automatically; it appears in the approving user’s token list, where it can be revoked, and is used as a bearer token for subsequent API calls.

Connecting MCP clients

The Omnara API is also exposed as an MCP server at https://app.omnara.com/mcp. MCP clients that support the MCP authorization spec discover the OAuth endpoints themselves and sign you in through the browser, so no token needs to be pasted into the client. Add the server to your client’s mcp.json:

{
  "mcpServers": {
    "omnara": {
      "type": "http",
      "url": "https://app.omnara.com/mcp"
    }
  }
}

On first use the client opens the dashboard’s Authorize access to Omnara page. Approve it and the client stores its own short-lived tokens, refreshing them in the background. Clients without OAuth support can pass a personal access token or org API key instead:

{
  "mcpServers": {
    "omnara": {
      "type": "http",
      "url": "https://app.omnara.com/mcp",
      "headers": { "Authorization": "Bearer omnara_pat_v1_…" }
    }
  }
}

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

Connecting MCP clients

Managing tokens

​Using an API key

​Creating personal keys

​Org API keys for services

​Device login for CLIs

​Connecting MCP clients

​Managing tokens

Using an API key

Creating personal keys

Org API keys for services

Device login for CLIs

Connecting MCP clients

Managing tokens