---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/account/api-keys
markdown_url: https://steel.dev/docs/account/api-keys.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: API keys
description: Create an API key, send it in the steel-api-key header, choose between an organization key and a project key, and rotate it.
summary: Create an API key, send it in the steel-api-key header, choose between an organization key and a project key, and rotate it.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/account/projects.md
  - https://steel.dev/docs/account/organizations-and-members.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# API keys

An API key lets your code call Steel. The API, the Steel SDK, the Steel CLI and the MCP server all accept it. A key belongs to your organization, and its scope decides which projects it reaches.

An API key does not log a browser in to a website. For that, see [Profiles](https://steel.dev/docs/logins/profiles) and [Credentials](https://steel.dev/docs/logins/credentials).

## Create a key

1. Sign in to the dashboard at [app.steel.dev](https://app.steel.dev).
2. Open **API Keys** in the sidebar, under **Organization** ([direct link](https://app.steel.dev/settings/api-keys)).
3. Click **Create API key**.
4. Under **Name your key**, type a name that says where the key runs, such as `production`, `ci` or `local-dev`.
5. Under **Scope**, choose **Project key** or **Organization key**. For a project key, choose the project under **Project**. [Choose a scope](https://steel.dev/docs/account/api-keys#choose-a-scope) explains the difference.
6. Click **Create API key**, and then **Copy**. The key starts with `ste-`.

> **Warning**
>
> Steel shows the full key only once, when you create it. If you lose it, revoke the key and create a new one.

Export the key as `STEEL_API_KEY` in your shell:

```sh
export STEEL_API_KEY=ste-your-api-key
```

The `curl` command and the programs on this page read the key from there. To keep the key in a `.env` file instead, load the file when you run a program, for example with Node's `--env-file=.env` flag or the `python-dotenv` package. Add `.env` to your `.gitignore` file so that the key never reaches version control.

To check the key, send it to the API:

```sh
curl -i https://api.steel.dev/v1/sessions \
  -H "steel-api-key: $STEEL_API_KEY"
```

A `200 OK` response means that Steel accepts the key. A `401` response means that the key is wrong or missing.

[Stripe Projects](https://steel.dev/docs/integrations/stripe-projects) can provision a key for you. The [Steel CLI](https://steel.dev/docs/control/cli) needs no key when you sign in with `steel login`.

## Send the key

Each interface takes the key in its own place:

| Interface | Where the key goes |
| - | - |
| API | The `steel-api-key` header |
| Steel SDK | The `STEEL_API_KEY` environment variable, or the `steelAPIKey` option (`steel_api_key` in Python, `option.WithSteelAPIKey` in Go and `api_key` in Rust) |
| CDP connection | No key. Connect to the session's `websocketUrl`, which holds a token for that session. |
| Steel CLI | The `STEEL_API_KEY` environment variable. After `steel login`, the CLI needs no key. |
| MCP server | No key when your client signs in. Otherwise, the `Authorization: Bearer` header or the `steel-api-key` header. See [MCP server](https://steel.dev/docs/control/mcp-server#use-an-api-key). |

This program reads the key from `STEEL_API_KEY` and prints the projects that the key reaches.

**TypeScript**

```ts file=check-key.mts
import Steel from "steel-sdk";

const client = new Steel();
const { projects } = await client.projects.list();

for (const project of projects) {
  console.log(project.name);
}
```

**Python**

```python file=check_key.py
from steel import Steel

client = Steel()
response = client.projects.list()

for project in response.projects:
    print(project.name)
```

**Go**

```go file=main.go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()
	response, err := client.Projects.List(ctx)
	if err != nil {
		return err
	}

	for _, project := range response.Projects {
		fmt.Println(project.Name)
	}
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();
    let projects = client.projects().list().await?.projects;

    for project in projects {
        println!("{}", project.name);
    }
    Ok(())
}
```

Run the program:

**TypeScript**

```sh
npx tsx check-key.mts
```

**Python**

```sh
python check_key.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

With a project key, the program prints the key's project. With an organization key, it prints every project in the organization.

```text nocopy
Default project
```

## Choose a scope

| Scope | What it reaches | Who can create it |
| - | - | - |
| Project key (`project`) | One project. Every request uses that project, even if it names another `projectId`. | Any member, in the dashboard. An organization key, through the API. |
| Organization key (`global`) | Every project of the organization. A request that creates a session, runs a Quick action, or works with profiles or credentials must name a project in `projectId`. A list of sessions covers every project unless you name one. | An organization admin, in the dashboard |

A new key is a project key unless you choose the `global` scope, which the dashboard calls **Organization key**. The dashboard lists keys under **Project keys** and **Organization keys**. Use project keys for your applications, because a leaked project key exposes one project, not the whole organization. Keep an organization key for the code that manages other keys, such as a provisioning script. [Organizations and members](https://steel.dev/docs/account/organizations-and-members) shows how to make a member an admin. [Projects and namespaces](https://steel.dev/docs/production/projects-and-namespaces) explains what a project holds.

## Create project keys from the API

With an organization key, you can create project keys through the API. Use this to give each customer, environment or worker its own key. A project key cannot create keys, and an organization key cannot create other organization keys.

Put an organization key in `STEEL_API_KEY` and the target project's ID in `STEEL_PROJECT_ID`. [Projects](https://steel.dev/docs/account/projects) shows how to find the ID.

**TypeScript**

```ts file=create-key.mts
import Steel from "steel-sdk";

const client = new Steel();

const apiKey = await client.apiKeys.create({
  projectId: process.env.STEEL_PROJECT_ID,
  name: "ci",
});

console.log(apiKey.id, apiKey.scopeType, apiKey.projectId);
```

**Python**

```python file=create_key.py
import os

from steel import Steel

client = Steel()

api_key = client.api_keys.create(
    project_id=os.environ["STEEL_PROJECT_ID"],
    name="ci",
)

print(api_key.id, api_key.scope_type, api_key.project_id)
```

**Go**

```go file=main.go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()

	apiKey, err := client.APIKeys.New(ctx, steel.APIKeyNewParams{
		ProjectID: steel.F(os.Getenv("STEEL_PROJECT_ID")),
		Name:      steel.F("ci"),
	})
	if err != nil {
		return err
	}

	fmt.Println(apiKey.ID, apiKey.ScopeType, apiKey.ProjectID)
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();

    let api_key = client
        .api_keys()
        .create(steel_rs::ApiKeyCreateParams {
            project_id: Some(std::env::var("STEEL_PROJECT_ID")?),
            name: Some("ci".to_owned()),
            ..Default::default()
        })
        .await?;

    let project_id = api_key.project_id.unwrap_or_default();
    println!("{} {:?} {project_id}", api_key.id, api_key.scope_type);
    Ok(())
}
```

Run the program:

**TypeScript**

```sh
npx tsx create-key.mts
```

**Python**

```sh
python create_key.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

The program prints the new key's ID, scope and project.

The full secret is in the `key` field of the response, and only in this response. Store it in your secret store as soon as you create it. Do not print it or log it.

The new key does not depend on the key that created it. If you revoke the organization key, the project keys that it created keep working. Every field of the request is on [API keys API](https://steel.dev/docs/reference/api/api-keys).

## Rotate a key

Rotate a key on a schedule, and at once if it might have leaked. To rotate a key without downtime:

1. Create a new key with the same scope, in the dashboard or with [the API](https://steel.dev/docs/account/api-keys#create-project-keys-from-the-api).
2. Put the new key everywhere that uses the old one: environment variables, secret stores and CI.
3. Check that your traffic uses the new key. In the dashboard, the **Last used** time of the new key changes.
4. [Revoke](https://steel.dev/docs/account/api-keys#revoke-a-key) the old key.

The **Rotate** button on a key's row is faster, but it is not free of downtime. It gives you a new key with the same name, scope and project, and the old key stops working at once. Use it when the old key might have leaked. Only an admin can rotate an organization key.

Give each environment its own key, so that you can rotate one without the others.

A key that you created with [Stripe Projects](https://steel.dev/docs/integrations/stripe-projects) rotates through Stripe Projects, not in the dashboard.

## Revoke a key

To revoke a key, open the dashboard's [API Keys page](https://app.steel.dev/settings/api-keys), click the trash icon on the key's row, and click **Yes, delete**. Steel revokes it at once, and each request that still uses it gets a `401` response. You can revoke keys only in the dashboard. The API cannot list or delete keys.

If [Stripe Projects](https://steel.dev/docs/integrations/stripe-projects) created the key, revoking it also removes the Steel service from your Stripe project. The Steel project stays. Only `stripe projects remove` deletes it.

## Check that it worked

Send the `curl` command in [Create a key](https://steel.dev/docs/account/api-keys#create-a-key) with each key that you use. A key that works gets `200 OK`. A key that you created from the API has `scopeType` set to `project`, and its `projectId` is the ID in `STEEL_PROJECT_ID`. After you revoke a key, the same command with the old key gets `401`.

## Troubleshooting

### `invalid_api_key`

```text nocopy
Invalid Steel API key. The key sent in the 'steel-api-key' header does not match any account. Create or rotate a key at https://app.steel.dev/settings/api-keys.
```

**Cause:** The key does not match an active key. It has a typo or a space at the end, it comes from the wrong environment variable, or someone revoked it.

**Fix:** Copy the key again from your secret store, or create a new key. If you changed `STEEL_API_KEY`, restart the process, because a running process keeps the old value.

**Verify:** The `curl` command in [Create a key](https://steel.dev/docs/account/api-keys#create-a-key) returns `200 OK`.

### `missing_api_key`

```text nocopy
Missing API key. Send your Steel API key in the 'steel-api-key' header. Create or rotate a key at https://app.steel.dev/settings/api-keys.
```

**Cause:** The request has no `steel-api-key` header. The SDK client found no key, or a raw HTTP request left out the header.

**Fix:** Set `STEEL_API_KEY` in the process's environment, or pass the key to the client. In a raw request, add the `steel-api-key` header.

**Verify:** The request returns a `2xx` status.

### This API key is scoped to the whole organization

```text nocopy
This API key is scoped to the whole organization, so it binds to no project. Pass projectId to say which project this request is for.
```

**Cause:** The request uses an organization key, and it does not name a project. An organization key reaches every project, so Steel cannot choose one.

**Fix:** Pass `projectId` in the request, or use a project key.

**Verify:** The request returns a `2xx` status, and the resource that it creates has the `projectId` that you passed.

## Next steps

- [Prepare for production](https://steel.dev/docs/production/checklist): Check that each environment has its own key, kept out of the code, before you launch.
