Authenticate requests

OpenMetal has two credential classes. They are not interchangeable.

Project API keys

Use a project key for sandbox lifecycle, operations, processes, files, and leased HTTP endpoints.

Authorization: Bearer metal_sk_your_key
X-Metal-Project-ID: prj_your_project

The operation read and event routes require the exact project key that created the sandbox, but they do not require X-Metal-Project-ID.

Project keys are returned once when created. Store them in a secret manager or the CLI credential store.

User access tokens

Use an OpenMetal user access token to manage organizations, members, projects, API keys, provider credentials, billing, usage, webhooks, and durable project events.

Authorization: Bearer <openmetal-user-access-token>

The dashboard and CLI create and refresh this session after you sign in. Advanced SDK integrations can provide a token callback:

const controlPlane = new MetalClient({
  baseUrl: process.env.OPENMETAL_API_URL!,
  accessToken: () => process.env.OPENMETAL_ACCESS_TOKEN,
});

Security checklist

• Keep credentials out of repositories and browser bundles.
• Never place a token inside sandbox metadata, environment configuration, or process arguments.
• Rotate project keys and give each workload its own key.
• Treat one time key output as sensitive terminal output.

See the API reference for route specific security requirements.