Authenticate to the Runtime API

Spinup's direct runtime API is scoped to one Spinup Agent. See Spinup Agents and Runs for the concepts. You do not use a workspace API key or personal/device key for runtime calls; use an agent runtime key directly or configure @getspinup/sdk with that sk_agent_... key.

Issue an agent runtime key

Issue a runtime key from a control-plane credential, then copy it. The plaintext key is shown once. Issuing another key replaces the current runtime key for that agent.

From the SDK:

const issued = await spinup.agents.runtimeKey.issue({
  agentSlug: "support-agent",
});

console.log(issued.agentId, issued.apiKey);

Or call the public control-plane API directly:

curl -sS -X POST "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/runtime-key" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..."

You can also open the target agent in the Spinup dashboard, go to Access, and issue a runtime key there.

Send the key as a bearer token:

curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../status" \
  -H "Authorization: Bearer sk_agent_0123456789abcdef..."

Use the right credential

• Workspace API key (sk_workspace_...): authenticates SDK or direct API calls for one workspace
• Personal/device key (sk_user_...): authenticates CLI login for a user and can switch workspaces
• Agent runtime key (sk_agent_...): authenticates directly to one agent runtime for /status and /runs

The issue response includes agentId. Use that durable ID in runtime URLs such as /v1/agents/{agentId}/status; the human-facing agent slug is only for control-plane workspace routes.

When to use the runtime API

Use the runtime API when your application needs to:

• check whether an agent environment is ready
• run prompts against an existing agent
• target one agent from backend code or automation
• read support-safe run history for that agent