Skip to content

API keys

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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 and Credentials.

Create a key

  1. Sign in to the dashboard at app.steel.dev.
  2. Open API Keys in the sidebar, under Organization (direct link).
  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 explains the difference.
  6. Click Create API key, and then Copy. The key starts with ste-.

Export the key as STEEL_API_KEY in your shell:

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:

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 can provision a key for you. The Steel CLI needs no key when you sign in with steel login.

Send the key

Each interface takes the key in its own place:

InterfaceWhere the key goes
APIThe steel-api-key header
Steel SDKThe STEEL_API_KEY environment variable, or the steelAPIKey option (steel_api_key in Python, option.WithSteelAPIKey in Go and api_key in Rust)
CDP connectionNo key. Connect to the session's websocketUrl, which holds a token for that session.
Steel CLIThe STEEL_API_KEY environment variable. After steel login, the CLI needs no key.
MCP serverNo key when your client signs in. Otherwise, the Authorization: Bearer header or the steel-api-key header. See MCP server.

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

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);
}

Run the program:

npx tsx check-key.mts

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

Default project

Choose a scope

ScopeWhat it reachesWho 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 shows how to make a member an admin. 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 shows how to find the ID.

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);

Run the program:

npx tsx create-key.mts

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.

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.
  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 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 rotates through Stripe Projects, not in the dashboard.

Revoke a key

To revoke a key, open the dashboard's API Keys page, 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 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 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

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 returns 200 OK.

missing_api_key

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

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