> ## Documentation Index
> Fetch the complete documentation index at: https://docs.errorbar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every request with a workspace API key — and understand what each key is allowed to do.

Omnia authenticates with **API keys** passed as a Bearer token. One key works
for everything: inference, and the whole management API (logs, judges, evals,
training, dedicated endpoints, aliases).

## Creating a key

1. Open the [dashboard](https://platform.omnia-voice.com/dashboard) → **API keys**.
2. Click **Create key**, give it a name, and copy the value.

<Warning>
  Your key is shown **once**, at creation. Omnia stores only a hash and can't
  show it to you again. If you lose it, revoke it and create a new one.
</Warning>

Every key belongs to a workspace. All usage, billing, and resources created
with a key are scoped to that workspace.

## Using a key

Send it in the `Authorization` header as a Bearer token:

```bash theme={null}
Authorization: Bearer sk_sovereign_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

With the OpenAI SDK, set it as the `api_key`:

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://gateway.omnia-voice.com/v1",
      api_key="sk_sovereign_...",
  )
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://gateway.omnia-voice.com/v1",
    apiKey: process.env.OMNIA_API_KEY,
  });
  ```
</CodeGroup>

## Key format and failures

Omnia keys always start with `sk_sovereign_`. A missing, malformed, or
revoked key returns `401` with the standard envelope, so one parser handles
auth failures and every other refusal:

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

The cheapest way to verify a key works, and see which workspace it lands in,
is `GET /v1/setup/status`: a `200` proves the key is live and reports where
your workspace is in the setup, including what to do next. Send
`Accept: text/plain` for flat `key=value` lines if you're parsing from a
shell script.

## Key permissions and roles

A key is not just a workspace pointer. Every key **acts as the user who
minted it**, and permission checks run against that user's workspace role per
operation:

* **Read endpoints** work with any workspace key. (The training surfaces:
  GRPO, RAFT rounds, environment tools, and model versions, are the
  exception: they require owner/admin even to read.)
* **Endpoints that spend money or redirect traffic** require the minting user
  to be a workspace **owner or admin**, and return `403` otherwise: creating
  dedicated endpoints, fine-tuning jobs, GRPO runs, eval runs, datasets,
  labels, judges and anything that judges (calibration, scans, suggestions,
  auto-improve), and alias repoints.

The practical consequence: a key minted by a regular member is a safe
read-and-infer credential, and revoking a person's admin role also downgrades
what their existing keys can do. Mint CI keys from an admin account
deliberately, not by accident.

Money-creating endpoints additionally carry a per-workspace abuse guard
(default 20 requests per 60 seconds); past it you get `429` with a
`Retry-After` header.

## Revoking a key

Revoke any time from the dashboard. Revocation is checked on every request,
so it takes effect immediately: there is no cached session to wait out. Each
key's last-used time is tracked, which makes stale keys easy to spot before
you rotate.

<Note>
  Provider keys for [bring your own key](/reference/bring-your-own-key) are a
  separate thing: they are stored encrypted and write-only, and never work as
  Omnia API keys.
</Note>

## Best practices

<AccordionGroup>
  <Accordion title="Never commit keys to source control" icon="lock">
    Load keys from environment variables or a secrets manager. A key in a public
    repo should be treated as compromised: revoke it.
  </Accordion>

  <Accordion title="Use separate keys per environment" icon="layer-group">
    Create distinct keys for development, staging, and production so you can
    revoke one without affecting the others, and attribute usage clearly. The
    per-key table in [Observability](/reference/observability) shows exactly
    which key is doing what.
  </Accordion>

  <Accordion title="Rotate periodically" icon="rotate">
    Create a new key, roll your services over to it, then revoke the old one.
    Last-used timestamps confirm the old key has gone quiet before you revoke.
  </Accordion>
</AccordionGroup>