Authentication

Firedrill API requests use an opaque bearer credential:

Authorization: Bearer <Firedrill credential>

Treat it as a secret. Never put it in repository configuration, recipes, target input, captured evidence, logs, or a coding agent’s chat. Run firedrill login. The CLI starts a device/browser authorization flow with WorkOS. A person approves the identity and organization; the client then exchanges that approved session for Firedrill authority. The CLI and native SDKs use a protected owner-only login store outside your repository. They preserve pending exchange and refresh state for exact recovery. Do not delete that state to retry a network failure. WorkOS identity tokens belong only at the sign-in boundaries. They are not general Firedrill API credentials. If your signed-in identity or organization changes, stop the client, verify the intended context, and reconnect deliberately. Recover existing work under its original authority. Connect your MCP host to https://mcp.firedrill.run/mcp, then use its OAuth sign-in action. A person approves access through WorkOS in the browser. The host stores the resulting OAuth credential; it does not belong in a prompt, repository MCP file, or recipe. See native host setup. The MCP host and CLI have separate sign-in sessions. Authorize the CLI or SDK when it needs to run the actual application locally, using the same intended organization. Do not copy a host’s credential into another client. Authentication never starts the application or approves its model-provider credentials.

Scoped credentials for CI

Use a scoped machine credential for unattended execution. An authorized human sign-in with credentials:manage can issue one through POST /v1/credentials or the CLI’s firedrill credentials commands. Choose one project/environment pair, an explicit capability subset, and an expiry. A machine credential cannot issue or manage other credentials, and cannot receive more authority than its issuer.

Capability	Use
`read`	Discover and inspect authorized resources and evidence.
`runs:write`	Submit/cancel batches and save scenario revisions.
`runs:execute`	Coordinate actual customer-runner attempts.
`assessments:create`	Request assessments or candidate recommendations.
`services:publish`	Publish private Tool source/data or acquire a catalog release.
`services:create`	Allocate controlled Tool instances.
`services:invoke`	Invoke explicitly granted Tool operations.
`services:control`	Perform permitted Tool lifecycle and connection actions.

Grant only the capabilities your workflow needs. Tool-bound simulations need the applicable Tool capabilities as well as run authority. Declaring a capability in a recipe or config file grants nothing. Store the issued token directly in your CI secret store as FIREDRILL_TOKEN. Credential lists return metadata, not secrets. Exact issuance replay has a bounded protected secret-recovery window; if it has ended, inspect and revoke that credential before intentionally issuing a replacement.

Native client configuration

Both clients connect to https://api.firedrill.run. Select the exact IDs returned by the project list or saved by firedrill init.

import { Firedrill } from "@firedrill-run/sdk";

const client = new Firedrill({
  projectId: process.env.FIREDRILL_PROJECT_ID,
  environmentId: process.env.FIREDRILL_ENVIRONMENT_ID,
});

import os
from firedrill import Firedrill

client = Firedrill(
    project_id=os.environ["FIREDRILL_PROJECT_ID"],
    environment_id=os.environ["FIREDRILL_ENVIRONMENT_ID"],
)

Set both scope variables before running these examples. The clients read FIREDRILL_TOKEN for automation, or use protected sign-in when no explicit token is supplied. An explicitly supplied invalid token is not silently replaced by a different sign-in. Keep credentials out of firedrill.config.json. For a direct API request:

curl "https://api.firedrill.run/v1/context" \
  --header "Authorization: Bearer ${FIREDRILL_TOKEN}"

Tool grants are not API credentials

Your target receives only the Tool connections selected for its run: exact instance, epoch, audience, allowed operations, and lifetime. It must not receive the coordinating API credential, controller-only operations, or evaluation rubric. HTTP, MCP, and browser audiences are checked separately. A Tool token cannot read another run’s report, manage projects, or issue credentials. Current parent authority, actor ownership, instance state, and operation grants are checked at issuance and use. Reusable Tool connections return their token or browser launch URL once. Replaying connection creation returns retained metadata without the secret. If the first response was lost, inspect and explicitly revoke that connection before issuing another with its own operation key. Resetting an instance advances its epoch and invalidates prior connections; extending compute lifetime does not renew them.

Expiry and revocation

On 401, inspect whether your sign-in or machine credential expired or was revoked. Use the supported login flow or explicitly authorized replacement; do not repeatedly submit the same invalid authority. Signing out ends the interactive session, not separately issued machine credentials. Revoke machine credentials by their exact retained ID when they are no longer needed. Revocation does not erase run history or evidence.

Overview

Control API

Scoped credentials for CI

Native client configuration

Tool grants are not API credentials

Expiry and revocation

​Human-approved sign-in

​Coding-agent MCP sign-in

​Scoped credentials for CI

​Native client configuration

​Tool grants are not API credentials

​Expiry and revocation

Human-approved sign-in

Coding-agent MCP sign-in

Scoped credentials for CI

Native client configuration

Tool grants are not API credentials

Expiry and revocation