# Authentication

API key types, generation, and how to authenticate requests

To access the SteelEngine API, you need an API key. SteelEngine supports three types of API keys — **personal keys**, **workspace keys**, and **organization keys** — each with different billing and access behaviors.

For self-hosted deployment pipelines using Entra application tokens, use the [platform MCP endpoint](/mcp/steelengine) and [workload identity guide](/self-hosting/entra-workload-identities). That Bearer path supports selected automation operations; it does not enable Entra authentication on the generic REST endpoints or change the API-key SDKs documented here.

## Key Types

|                   | **Personal Keys**                    | **Workspace Keys**                      | **Organization Keys**                                          |
| ----------------- | ------------------------------------ | --------------------------------------- | -------------------------------------------------------------- |
| **Billed to**     | Your individual account              | Workspace owner                         | Workspace owner                                                |
| **Scope**         | Across workspaces you have access to | Shared across the workspace             | Explicit grants: chosen workspaces and/or individual workflows |
| **Managed by**    | Each user individually               | Roles with workspace API-key management | Roles with `organization:manage_api_keys`                      |
| **Authorization** | Owner PBAC plus workspace policy     | Owner PBAC plus workspace key scope     | Owner PBAC plus explicit per-grant key scope                   |

A role with workspace settings authority can disable personal API key usage for that workspace. If disabled, only workspace and organization keys can be used.

### Scoped keys

Workspace keys can optionally be narrowed to **specific workflows** at creation time. Organization keys always carry an explicit scope list — each grant targets a workspace or a single workflow and carries a read, write, or admin transport ceiling. The owner's PBAC permission and the key grant must both allow a request. A key used outside its grants is rejected. Endpoints that check the key against a specific workflow while authenticating it, such as execute, cancel, and deploy, answer `401`. The `/api/v1` resource endpoints answer `403`. An organization key loses access to a workspace that leaves the organization.

## Generating API Keys

To generate a personal or workspace key, open the SteelEngine dashboard and navigate to workspace **Settings → API Keys** and click **Create**. Organization keys are managed in **Organization Settings → API Keys** by a role with `organization:manage_api_keys`; the workspace settings page also lists which organization keys can reach the current workspace.

API keys are only shown once when generated. Store your key securely — you will not be able to view it again.

## Using API Keys

Pass your API key in the `X-API-Key` header with every request. For the execute endpoint, the body's top-level fields are the workflow's input:

**curl**

```bash
curl -X POST https://steelengine.com/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "Hello"}'
```

**TypeScript**

```typescript
const response = await fetch(
  'https://steelengine.com/api/workflows/{workflowId}/execute',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.STEELENGINE_API_KEY!,
    },
    body: JSON.stringify({ message: 'Hello' }),
  }
)
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://steelengine.com/api/workflows/{workflowId}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["STEELENGINE_API_KEY"],
    },
    json={"message": "Hello"},
)
```

## Public API Access

A deployed workflow can also run without any credentials. To allow this:

1. Open the workflow's **Deploy** modal.
2. Open the **API** tab.
3. Click **Edit API Info**.
4. Set **Access** to **Public**. The default is **API Key**.

The dashboard warns that anyone can then call the endpoint. All usage is billed to the workflow's owner. If your deployment has public APIs disabled, the **Access** control is not shown.

You can also change this setting with [Update Deployment Settings](/api-reference/workflows/updateDeploymentSettings). Successful updates record a `workflow.public_api_updated` audit event with the actor and previous/new `isPublicApi` values. Requests authenticated by an API key also record its ID and type, so you can identify which key changed public access.

Public calls run as the workflow's owner, against the deployed state only:

* A request that carries an `X-API-Key` header or a `Bearer` token is authenticated as that credential instead. An invalid key still returns `401`.
* Only the deployed version runs. SteelEngine ignores `useDraftState`. Pinning a version with the `X-SteelEngine-Deployment-Version` header returns `403`.
* `isClientSession` returns `400`. SteelEngine drops workflow state overrides.
* The workflow must stay deployed. Public calls fail with `401` if you undeploy it, switch **Access** back to **API Key**, or disable public APIs for the owner's account.

Public access bills every call to the owner's account. Leave it on **API Key** unless the workflow is meant to be called anonymously.

## Where Keys Are Used

API keys authenticate access to:

* **Workflow execution** — run deployed workflows via the API
* **Deployments** — deploy, undeploy, and roll back workflows. Deploying needs a workspace admin owner, and an admin grant on scoped keys
* **Logs API** — query workflow execution logs and metrics
* **MCP servers** — authenticate connections to deployed MCP servers
* **SDKs** — the [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) SDKs use API keys for all operations

## Security

* Keys use the `sk-steelengine-` prefix and are encrypted at rest
* Keys can be revoked at any time from the dashboard
* Use environment variables to store keys — never hardcode them in source code
* For browser-based applications, use a backend proxy to avoid exposing keys to the client

Never expose your API key in client-side code. Use a server-side proxy to make authenticated requests on behalf of your frontend.
