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 and workload identity guide. 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 KeysWorkspace KeysOrganization Keys
Billed toYour individual accountWorkspace ownerWorkspace owner
ScopeAcross workspaces you have access toShared across the workspaceExplicit grants: chosen workspaces and/or individual workflows
Managed byEach user individuallyRoles with workspace API-key managementRoles with organization:manage_api_keys
AuthorizationOwner PBAC plus workspace policyOwner PBAC plus workspace key scopeOwner 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 -X POST https://dev.steelengine.com/api/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"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. 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 and 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.

On this page