---
title: "Creating and managing API keys"
description: "Create, scope, track, and revoke API keys — and keep them secure."
url: https://help.samsa.ai/en/articles/143-creating-and-managing-api-keys
collection: "API & MCP"
updated: 2026-07-07
language: en
alternates: [de, fr, it]
---

# Creating and managing API keys

Create, scope, track, and revoke API keys — and keep them secure.

## 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

1.  Go to **Organization Settings** > **API Keys** and click **Create API key**.
    
2.  Give the key a **name** you'll recognize later — for example, "CI pipeline" or "Zapier".
    
3.  Choose the **scopes** (permissions) the key should have — pick only what it needs (see below).
    
4.  Set when the key **expires** — 30 days, 90 days, 1 year, Never, or a custom date.
    
5.  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:

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Scope</p></th><th colspan="1" rowspan="1"><p>What it allows</p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>Generate images</strong></p></td><td colspan="1" rowspan="1"><p>Create new images and check their status</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Edit images</strong></p></td><td colspan="1" rowspan="1"><p>Edit existing images and check edit status</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Generate videos</strong></p></td><td colspan="1" rowspan="1"><p>Create new videos and check their status</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Read models</strong></p></td><td colspan="1" rowspan="1"><p>List and view your organization's models</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Manage models</strong></p></td><td colspan="1" rowspan="1"><p>Create, update, and delete models</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Read usage</strong></p></td><td colspan="1" rowspan="1"><p>Read the credit balance and usage data</p></td></tr></tbody></table>

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](https://docs.samsa.ai/guides/authentication) in the developer docs (opens in a new tab).
