Skip to main content
Every request needs a Voyager API key in the Authorization header:
A request without a valid key returns 401 with error code invalid_api_key and a WWW-Authenticate: Bearer header.

​
Create a key

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.
1

Open the API tab

Sign in at 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

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:
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, 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. 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.

​
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 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.