Creating and Managing API Keys
An API key is what lets a tool, script, or AI assistant act on behalf of your organization. Keys are created and managed inside Samsa by owners and admins.
Where to find API keys
Open Organization Settings > API Keys. Only organization owners and admins can manage keys — if you don't see the tab, ask an admin for access.
Creating a key
Go to Organization Settings > API Keys and click Create API key.
Give the key a name you'll recognize later — for example, "CI pipeline" or "Zapier".
Choose the scopes (permissions) the key should have — pick only what it needs (see below).
Set when the key expires — 30 days, 90 days, 1 year, Never, or a custom date.
Click Create key.
Copy your key right away. Samsa shows the full key only once, in a dialog titled "Your new API key." For security, only a hash is stored — if you lose the key, you can't recover it and will need to create a new one. Paste it straight into your tool or a secure secrets manager, then confirm "I stored the key in a safe place."
Every key starts with samsa_sk_, so it's easy to recognize.
Scopes (permissions)
Scopes keep each key limited to exactly what it needs. Samsa offers:
Scope | What it allows |
|---|---|
Generate images | Create new images and check their status |
Edit images | Edit existing images and check edit status |
Generate videos | Create new videos and check their status |
Read models | List and view your organization's models |
Manage models | Create, update, and delete models |
Read usage | Read the credit balance and usage data |
A key needs at least one scope. Give each key the fewest scopes it needs for its job — a key that only generates images doesn't need model-management access.
Watching a key's usage
The API Keys table shows each key's status (Active, Expired, or Revoked), who created it, when it expires, when it was last used, how many requests it has made, and the credits used (this period, last 30 days, or all time). Open a key to see a breakdown of credits by action type. Turn on Show revoked keys to include old ones.
Editing and revoking
Edit key lets you rename a key or adjust its scopes and expiry.
Revoke key switches it off. Integrations using that key stop working immediately, and revoking can't be undone — so revoke a key as soon as it's no longer needed or if it might have been exposed.
Keeping keys safe
Treat a key like a password. Never paste it into public code, screenshots, or shared chats.
Store it in a secrets manager, not in plain files.
Use least-privilege scopes and an expiry date rather than "Never" where you can.
Revoke unused keys and rotate keys periodically — create a new one, switch your tool over, then revoke the old one.
If a key is ever exposed, revoke it right away and create a replacement.
Need the technical details for using a key in requests? See the Authentication guide in the developer docs (opens in a new tab).