---
title: "Authentication"
description: "Bearer tokens, key creation, key rotation."
section: getting-started
order: 2
layout: guide
updated: "2026-05-27"
---

Token Factory uses API keys as Bearer tokens for OpenAI-compatible `/v1` requests. Keys carry the `sk-oais` prefix and inherit their workspace's quotas, billing, and Observability scope.

## Workspace-level controls

> **What is and isn't scoped per key**
>
> Most control surfaces sit at the **workspace** level. Expiry is the one you
> set on an individual key.
>
> **Scoped at workspace (apply to every key in the workspace):**
> - Token quotas and rate limits (RPM, TPM)
> - Billing and spend caps
> - Observability — usage, latency, and error metrics
>
> **Set per key:**
> - An optional expiry, chosen when you create the key — see [Key expiry and states](/docs/getting-started/authentication#key-expiry-and-states)
>
> **Not scoped per key:**
> - Per-key scopes or permissions
> - Per-key RPM / TPM overrides
> - Per-key spend caps
>
> If you need per-key isolation beyond expiry, use a separate workspace per workload.

  - **Header:** `Authorization: Bearer sk-oais...`
  - **Manage keys:** [API keys](/api-keys)
  - **Visibility:** Full secret appears once at creation. Lists show a mask keeping the first 8 and last 4 characters.
  - **Scope:** Selected workspace context.

## Create a key

  
#### Generate a key
Sign in to Token Factory and open [API keys](/api-keys). Enter a descriptive label, such as `prod-payments-worker` or `staging-pipeline`, and click **Generate**.

  
#### Choose an expiry
Optional. A new key **never expires** unless you say otherwise. Pick 30, 90
or 365 days, or **Pick a date…** for a specific day up to a year out. A key
with an expiry stops authenticating at 23:59 UTC on its last day, so it
works through the whole day you choose.

Ask for longer than the maximum permitted and creation fails with `400`
and the code `EXPIRY_TOO_LONG` — choose a shorter expiry and retry.

  
#### Copy the secret once
The full `sk-oais...` value is shown only once. Store it immediately in your password manager, CI/CD secret store, or runtime secret manager.

  
#### Set it locally
Use the same environment variable as the Quickstart examples.

**macOS / Linux**

```
export OMNIVA_API_KEY="sk-oais..."
```

**Windows PowerShell**

```
$env:OMNIVA_API_KEY="sk-oais..."
```

New keys use the `sk-oais...` prefix. Existing key lists show only a masked value (for example `sk-oaisf****************************************25xx` — first 8 and last 4 visible, rest hidden) so you can identify a key in logs and dashboards without exposing the full secret.

> **Store keys in environment variables, not source code**
>
> Never commit API keys. Use environment variables, secret managers, or your platform's secret bindings. Leaked keys end up in scrapers within minutes.

## Key expiry and states

A key in the list is in one of three states.

| State | What it means | Can you revoke it? |
| --- | --- | --- |
| **Active** | Authenticating normally. Shows `Never expires`, or the date it expires and how many days remain. | Yes |
| **Expired** | Passed its expiry and no longer authenticates. It stays in the list rather than vanishing, so you can see what lapsed. | Yes |
| **Disabled** | Switched off by an administrator. It no longer authenticates, and its masked secret is withheld. | No |

Keys inside **7 days** of expiring are badged **Expires soon**, which is the
window to create the replacement. Nothing rotates automatically — an expiry is
a deadline, not a hand-off, so treat the badge as the cue to run through
[Rotate a key](/docs/getting-started/authentication#rotate-a-key) before the
date rather than after it.

An expired key fails the same way a revoked or mistyped one does: the request
is rejected as unauthenticated, with no field distinguishing "expired" from
"invalid". If calls start failing and the key was on a timer, check its date in
[API keys](/api-keys) before assuming the secret is wrong.

## Required headers

Send API keys in the `Authorization` header.

| Header | Required | Notes |
| --- | --- | --- |
| `Authorization: Bearer <key>` | Yes | Use the full `sk-oais...` API key. |
| `Content-Type: application/json` | Yes (POST) | Required for JSON request bodies. |

## Security rules

  
**Rotate** — Create the replacement, deploy it, verify traffic, then revoke the old key.

  
**Keep out of URLs** — Send keys in headers only. URLs can be logged by browsers, proxies, and monitoring tools.

## Rotate a key

Rotation is **create-new, swap, revoke-old** — never revoke first.

  
#### Create the replacement
Open [API keys](/api-keys), generate a new key, and use a label that includes the workload and rotation date.

  
#### Deploy the new secret
Update the runtime secret in your service, CI/CD pipeline, or local environment.

  
#### Verify traffic
Confirm requests succeed with the new key and check [Observability](/docs/reference/observability-metrics) for unexpected errors.

  
#### Revoke the old key
After the new key is live everywhere, click **Revoke** next to the old key.

## A leaked key

Treat a leaked key as an incident:

1. **Revoke immediately** in [API keys](/api-keys).
2. **Generate a replacement** and roll it out to every affected environment.
3. **Check usage** in [Observability](/docs/reference/observability-metrics) for unexpected request volume.
4. **Audit every surface where the key may have been captured** — search for the leaked value or a stable prefix in:
    - Git history: `git log -S '<first 12 chars>'` and `git log -p -- <suspect files>`
    - CI/CD build logs (GitHub Actions, GitLab CI, Jenkins console output)
    - Slack and chat history (DMs and channels)
    - Error trackers that capture request headers (Sentry, Datadog, Rollbar)
    - Env-dump endpoints (`/health`, `/debug`, dev tools, internal admin pages)
5. **Notify your security team** using your internal incident process.

## Troubleshooting

> **Common authentication fixes**
>
> - `401 Unauthorized`: confirm the request includes `Authorization: Bearer sk-oais...` with the full key.
> - `403 Forbidden` while managing keys: confirm you are signed in with a workspace context that can manage API keys.
> - Unsupported sign-in provider: sign in with a supported workspace identity provider that can issue a JWT for API key management.
> - Key limit reached: revoke an unused key before generating a replacement.

## What next

  - [Quickstart](/docs/getting-started/quickstart) — Make your first call.
  - [Tokens, pricing & quotas](/docs/serverless/pricing) — Understand workspace-level usage controls.
  - [Observability](/docs/reference/observability-metrics) — Watch latency, spend, and errors per request.
  - [Errors & status codes](/docs/reference/errors) — What 401, 403, and 429 mean and how to recover.

