Authentication

All API requests require authentication via a Bearer token in the Authorization header. STACK supports three token types: operator API keys, team member keys, and session JWTs.

bash

curl -H "Authorization: Bearer sk_live_..." https://api.getstack.run/v1/agents

Authorization Header

Every request must include the Authorization header with a Bearer prefix. The token type is detected automatically by prefix:

sk_live_... -- API key (operator or team member)
eyJ... -- Session JWT (from dashboard magic link login)

bash

# Operator API key
curl -H "Authorization: Bearer sk_live_op_abc123..." https://api.getstack.run/v1/agents

# Team member key
curl -H "Authorization: Bearer sk_live_mem_def456..." https://api.getstack.run/v1/agents

# Session JWT (dashboard)
curl -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." https://api.getstack.run/v1/agents

Operator API Keys

Operator API keys (sk_live_...) are generated when you register via the dashboard. They have full access to all endpoints for your organization. The operator key is the master key -- it can manage team members, access all services, and perform administrative operations.

Team Member Keys

Team member keys are also prefixed with sk_live_. When a request arrives, STACK first checks if the key belongs to a team member. If not, it falls back to checking operator keys.

Member Roles

Team members have one of three roles that determine their access level:

readonly -- can read data but cannot create, update, or delete resources
standard -- can perform most operations, scoped to their allowed_connections list
admin -- full access within the organization, can manage team members and settings

Connection Restrictions

Members can be restricted to specific service connections via the allowed_connections list. When set, the member can only access credentials and services in that list. A 403 Forbidden is returned if they attempt to access a connection outside their allowed list.

Only the operator master key or a dashboard session JWT can manage team members (invite, revoke, update roles). Admin members can also manage team members. Standard and readonly member keys cannot.

Session JWTs

The dashboard uses EdDSA-signed session JWTs for browser authentication. These are issued via the passwordless magic link login flow. Session JWTs carry the sub (operator ID) and tier fields but do not carry the admin flag -- use an API key for admin operations.

Passport Tokens

For credential retrieval with accountability, include a passport token in theX-Passport-Token header. This enables security signals like scope checking and burst detection. The passport token is separate from the authentication token in the Authorization header.

bash

curl -H "Authorization: Bearer sk_live_..." \
     -H "X-Passport-Token: eyJ..." \
     https://api.getstack.run/v1/credentials/slack

Never expose API keys in client-side code or public repositories. Use environment variables and server-side proxies. API keys are hashed before storage -- STACK cannot recover a lost key.