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

# Authentication

> Create a Voyager API key on the dashboard, send it as a Bearer token, and know what it can do and who can revoke it.

Every request needs a Voyager API key in the `Authorization` header:

```bash theme={"system"}
curl https://api.voyager.so/v1/account \
  -H "Authorization: Bearer $VOYAGER_API_KEY"
```

A request without a valid key returns `401` with error code [`invalid_api_key`](https://docs.voyager.so/api/errors#invalid_api_key) and a `WWW-Authenticate: Bearer` header.

## Create a key

> [!NOTE]
>
> **Before you start:** API keys are for paid Voyager plans, trials included. On Free, the **API** tab shows an upgrade prompt instead; workspace members who can't change the plan should ask an owner or admin. Plans are on [voyager.so/pricing](https://voyager.so/pricing).

**1. Open the API tab**

Sign in at [voyager.so/dashboard/api](https://voyager.so/dashboard/api), or open **API** in the dashboard's top bar. On a phone, it's in the profile menu. Check that the workspace you want is selected: a key belongs to one workspace.

**2. Create the key**

Click **Create API key** and give it a name you'll recognize later, such as `ci` or `my-app-prod`.

**3. Copy the key and the webhook secret**

The key (`vy_live_` followed by 64 hex characters) and its webhook signing secret (`whsec_…`) are shown **once**. Copy both now. Voyager stores only a hash of the key, so nobody can show it to you again. If you lose it, revoke it and create another.

**4. Put it in your environment**

```bash theme={"system"}
export VOYAGER_API_KEY=vy_live_...
```

In a project, keep it in an untracked `.env` file, add `VOYAGER_API_KEY=` to `.env.example`, and make sure `.env` is in `.gitignore`.

Check it worked:

```bash theme={"system"}
curl -s https://api.voyager.so/v1/account -H "Authorization: Bearer $VOYAGER_API_KEY"
```

You should see your workspace, plan and credits available.

## Who a key acts as

A key acts as **you, in one workspace**. Jobs it creates are paid from that workspace's Voyager credits and count toward your own [parallel generations](https://docs.voyager.so/api/rate-limits.md#concurrency), shared with the Voyager app. Jobs and files are visible to the person who created them: a job made with one of your keys can be read with any of your other live keys in the same workspace, so rotating a key doesn't strand your results.

## Scopes

Every key has the same fixed set of scopes. There is no scope picker.

| Scope | Allows |
| - | - |
| `media:generate` | Estimate and create jobs; use Cast in jobs |
| `uploads:write` | Upload and import files, manage Cast cards |
| `files:read` | Read and download files and outputs |
| `credits:read` | Read `GET /v1/account` |
| `tasks:read` | Read and list jobs |
| `tasks:cancel` | Cancel jobs |

A key can't change billing, invite members, or manage other keys. Treat it as a password anyway: anyone holding it can spend your workspace's credits.

## Limits

* Up to **25 active keys** per person per workspace.
* Requests are rate-limited per key. See [Rate limits and usage](https://docs.voyager.so/api/rate-limits.md).

## See, rotate and revoke keys

The **API** tab lists keys by name and prefix (`vy_live_ab12…`), with who created each, when, and when it was last used, plus credits used by each key over the last 30 days.

* **Anyone** can revoke their own keys.
* **Workspace owners and admins** see and can revoke everyone's keys in the workspace.
* **Removing a member** from the workspace revokes all of their keys.

Click **Revoke** to revoke a key. Revoking takes effect right away: requests with that key return `401` `invalid_api_key`, signed result links issued to it stop working, and webhooks it hasn't delivered yet are dropped. Jobs it already started still finish and are still charged; read them with another of your keys.

To rotate a key: create a new one, deploy it, then revoke the old one. Retrying a request with the same `Idempotency-Key` from the new key still returns the original job, so a rotation in the middle of a retry never buys twice.

## If your plan changes

If your workspace moves to Free, your keys are kept. These keep working:

* reading and listing jobs, and downloading their results,
* cancelling work that was already accepted, deleting files, and managing Cast cards,
* `GET /v1/account`, which reports `plan.paid: false`,
* listing and revoking keys on the dashboard.

Anything that starts new paid work (creating jobs, estimates, uploads) returns `402` [`paid_plan_required`](https://docs.voyager.so/api/errors#paid_plan_required) with an `upgrade_url`. Upgrade and the same keys work again.

## Keep keys safe

* Never commit a key, paste it into an issue, or ship it in a browser, mobile app or other client code. Call the API from a server.
* Use one key per app or environment, so you can revoke one without touching the rest.
* Revoke keys you no longer use.
* If a key leaks, revoke it on the **API** tab first, then replace it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.