# API Keys

> Create scoped, rotatable API keys for programmatic access to the platform, with a grace window on rotation and immediate revoke—an alternative to username/password login.

Source: https://totalshiftleft.ai/help-center/product-documentation/api-keys

## Overview

This guide walks you through the **API Keys** screen in Shift Left Studio exactly as it appears, from creating a scoped key to rotating and revoking it. An **API key** gives external systems (CI/CD, scripts, integrations) programmatic access to the platform API without a username and password. Each key carries a set of **scopes** (permissions), can have an optional expiry, and can be rotated or revoked at any time.

Explore the capability at [api keys](/features/collaboration-security/api-keys).

**Availability:** Professional and Enterprise (same as the [Public API](/help-center/product-documentation/public-api)).

## Before you begin

- You must be an administrator with the **manage_api_keys** permission. For safety, **API keys cannot manage other API keys** — a request authenticated by an API key is rejected with *"API keys cannot manage API keys."*
- Navigate to **Settings → Access & Identity → API Keys**.
- The full secret is shown **exactly once**, right after you create or rotate a key. Copy it immediately and store it in a secret manager — it cannot be retrieved later.
- If the capability isn't available on your edition, the screen shows *"API keys are not enabled on this edition."*

## Step 1 — Create a key

1. In the **Create API Key** card (subtitle *"Name the key, optionally set an expiry, and choose the scopes it should grant."*), fill:

| Field | What it does |
|-------|--------------|
| **Name** | A label for the key (required), e.g. *CI pipeline*. The **Create API Key** button stays disabled until you enter a name. |
| **Expires in (days, optional)** | Number of days until the key expires. Leave blank (placeholder **Never**) for no expiry. Must be a positive number. |
| **Scopes** | The permissions the key may use, grouped by category. Click a checkbox to toggle each scope; the counter shows **N selected**. If the scope catalog can't load, you'll see *"Scope catalog is unavailable. The key will be created with no scopes; you can manage scopes later."* |

2. Click **Create API Key** (it shows **Creating…** while working). On success you'll see **"API key created."**

## Step 2 — Copy the one-time secret

1. A highlighted panel appears: **Your new API key for "<name>"** with the warning *"Copy this secret now — it will **not be shown again**. Store it somewhere safe."*
2. The full secret is shown in a monospace box. Click **Copy** — it changes to **Copied** for a couple of seconds. If the clipboard is blocked you'll see *"Could not copy to clipboard — copy it manually."*
3. Store the secret in your secret manager, then dismiss the panel with the **X** in its top-right corner. Once dismissed, the secret is gone for good.

## Step 3 — Rotate a key

Rotation issues a new secret while keeping the old one valid for a short grace window, so you can update clients without downtime.

1. In the keys table, click **Rotate** on the key's row. Confirm the prompt *"Rotate "<name>"? A new secret will be issued and shown once."*
2. The new secret appears in the same one-time reveal panel — **copy it immediately** (see Step 2).
3. The panel also notes the grace period: *"The previous secret remains valid until <date> (grace period)."* The grace window defaults to 1 day and is capped at 30 days. During rotation the key's status shows **rotating**.

## Step 4 — Revoke a key

- Click **Revoke** on the key's row and confirm *"Revoke "<name>"? This cannot be undone and will immediately stop working."*
- The key is invalidated **immediately** (no grace window) and its status becomes **revoked**. You'll see **"API key revoked."**

## The keys table

The table lists every key (the secret is never shown here):

| Column | What it shows |
|--------|---------------|
| **Name** | The key's label. |
| **Prefix** | The key's non-secret prefix, used to identify which key is which. |
| **Scopes** | The count of scopes granted to the key. |
| **Status** | **active** (green), **rotating** (orange), **expired** (grey), or **revoked** (red). |
| **Last used** | The date the key last authenticated (or **—**). |
| **Created** | The date the key was created. |
| **Actions** | **Rotate** and **Revoke** buttons. |

When there are no keys, the table reads *"No API keys yet. Create one above to get started."*

## Troubleshooting and notes

- **INVALID_NAME (400)** — no **Name** was supplied. Enter one.
- **UNKNOWN_SCOPES (400)** — one or more selected scopes aren't valid permissions. Re-open the scope picker and choose from the listed scopes.
- **KEY_NOT_ACTIVE (400)** — you tried to rotate a key that's already expired or revoked; only active keys can be rotated.
- **API_KEY_NOT_FOUND (404)** — the key was already deleted or belongs to another tenant.
- The list never returns the secret or its hash — only the prefix, scopes, status, and last-used time.
- All key actions (create, rotate, revoke) are written to the [audit log](/help-center/product-documentation/audit-logs).

## Related articles

- [Public API](/help-center/product-documentation/public-api)
- [Secret managers](/help-center/product-documentation/secret-managers)
- [Role Permissions](/help-center/product-documentation/role-permissions)
- [Audit Logs](/help-center/product-documentation/audit-logs)