---
title: "Create an API key"
method: POST
path: "/v1/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /v1/api-keys`

## Request

- Base URL: `https://api.steel.dev`
- URL: `https://api.steel.dev/v1/api-keys`
- Auth: API key in header `steel-api-key`

Create a project-scoped API key using a global (organization-scoped) API key. Supply projectId for an active project in the authenticated organization; scopeType must be project or omitted. Project-scoped API keys cannot create keys, and global keys cannot create other global keys. Dashboard users may also create project keys, or global keys with organization admin access. Returns the full secret once with Cache-Control: no-store; save it securely. The new key is independent: revoking the creating global key does not revoke keys it created. Missing projectId returns 400; insufficient scope returns 403; an unavailable or foreign project returns 404.

## Request body

- CreateAPIKeyRequest
  - `name` string: A human-readable label for the new key. Defaults to Default.
  - `projectId` string, uuid: The active project to bind the new key to, belonging to the authenticated organization. Required when authenticating with a global API key. Dashboard users may omit it to use their default project.
  - `scopeType` 'project' | 'global': Defaults to `project`. Global API keys may only create project-scoped keys. Only organization admins using dashboard authentication may create a `global` key; projectId is ignored for those keys.

## Response `201`

Default Response

- ApiKeyResponse
  - `createdAt` string, date-time, required
  - `id` string, uuid, required
  - `key` string, required: The full secret on creation or rotation only. Metadata reads return a masked preview. Store a newly created secret securely; it cannot be retrieved later.
  - `name` string
  - `projectId` string, uuid, nullable, required: The pinned project, or null for a global key, which binds to no project.
  - `scopeType` 'project' | 'global', required: `project` pins the key to one project. `global` authorizes access across the organization and has no project binding.
  - `updatedAt` string, date-time, required

## Other responses

- `400`: An error response from the API
- `401`: An error response from the API
- `403`: An error response from the API
- `404`: An error response from the API

## Changes

- **2026-10-16** `8f7e74e04bd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/steel-dev/apis/steel-api/changes/v1/api-keys/post.md)

---

[API](https://skmtc.dev/steel-dev/apis/steel-api.md) - [All operations](https://skmtc.dev/steel-dev/apis/steel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/steel-dev/apis/steel-api/revisions/8f7e74e04bd3?raw)