Authentication and API keys
Create a workspace key, select permissions, and store its secret.
Set up a key
- Open Developer in the dashboard account menu or command search.
- Use a workspace with a current paid plan. You must be its owner or an admin.
- Select Create API key at the top of the page to move to the setup form. Give the key a name and select its permissions.
- Submit the form. Focus moves to the secret panel beside the form. Copy the secret. Sovran shows it once.
- Store it in a secret store or a server environment variable.
- Select I saved this secret after you store it.
Use the key in the Authorization header. Keep it out of URLs, browser code, source control, and logs. The First request guide beside the form shows the API origin for the current host. Copy that origin into your server configuration. Make a first request.
Choose permissions
| Permission | Use |
|---|---|
read | Read workspace resources, results, and credits. |
write | Create and change content. |
generate | Render videos and use creation tools. |
delete | Delete permitted content after its guards pass. |
publish | Publish through dashboard connections. |
Delete and Publish start off. Use only the permissions your software needs. Start with Read for the first request. Add Write and Generate for the first-video example. Provider connections are required only for the features that use them.
Workspace, expiry, and revocation
Each key belongs to one workspace and its creator. Sovran checks its status, permissions, and the creator's current role on each request. The dashboard workspace selector does not change a key's workspace.
Active keys appear in the main list. Select Show key history to review expired and revoked keys. These keys cannot make new requests. Revocation stops new requests and explicit retries. Accepted jobs can finish after revocation.
Valid keys can read results and credits after plan expiry. New work needs a current paid plan. API access uses the same paid plan, credits, and feature charges as the dashboard.
Optional webhook secrets
Webhooks send job events to your HTTPS address. You can also read job results through the API without a webhook. Add a webhook in Developer. Save its signing secret from the panel beside the webhook form. Store that secret on the receiving server.
The signing secret is separate from the API key. Use it to verify each webhook request. Read the complete receiver example.
Recent deliveries show the receiver address, job reference, exact time, and result. Scheduled deliveries show their next attempt time.