Authentication and API Keys
Every Ideogram API request authenticates with an API key in the Api-Key header. Ideogram doesn’t offer scoped or restricted keys, and keys don’t expire. Keep the key in an environment variable on your server:
To create your first key, follow API Setup.
What a key can do
- Workspace-wide access. A key can call every generation endpoint its workspace can use and spend that workspace’s balance. An endpoint or model your organization can’t use returns
403. - Account endpoints need billing access.
GET /v2/account/usage,GET /v2/account/invoicesandGET /v2/account/api-keysanswer only keys created by someone who can see the workspace’s billing. Other keys get404. - Who pays. A request is billed to the workspace the key belongs to. On the Team plan, it uses the credits of the member who created the key. See which balance a key uses in the user guide.
- Shown once. Settings shows the full key only when you create it. Store it in a secret manager or environment variable, and keep it out of client-side code and public repositories.
- No expiry. A key works until you revoke it.
- Revocation is immediate and permanent. Revoke a key from Settings → API in the Ideogram app. Requests with it fail straight away, and it can’t be restored.
Separate environments
Keys in one workspace share its balance and access, so give each environment its own API team when you need separate balances or separate people. Each team has its own keys, credits and billing. Create one with Create an API team in the workspace switcher in Settings; see Teams.
In an API team:
- Members can create keys, see the team’s key list and use the team’s API, but can’t see Billing.
- Owners and Admins can also label and revoke keys, and manage billing and members.
Other workspace types, such as the Team plan and Enterprise agreements, handle keys differently; the user guide’s Ideogram API page compares them.
GET /v2/account/api-keys lists the keys on your account.
Rotate a key
- Create a new key in API Keys.
- Deploy it to every application that uses the old key.
- Confirm the applications work with the new key.
- Revoke the old key.
Revoking before every application has the new key stops those applications’ requests.