Authentication

All API requests require authentication via the Authorization header.

API keys

API keys are the recommended authentication method for server-to-server integrations.

Creating an API key

1. Log in to app.promptshuttle.com

2. Navigate to your Tenant Settings

3. Under API Keys, click Create API Key

4. Copy the key — it is only shown once

Using an API key

Pass your API key as a Bearer token:

curl https://app.promptshuttle.com/api/v1/chat/completions \
  -H "Authorization: Bearer ps_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API keys are scoped to your tenant. All requests made with a key are billed to that tenant and inherit its model routing rules, cost limits, and environment configurations.

Bearer tokens (JWT)

The web UI uses JWT bearer tokens obtained via the login endpoint. These are primarily for interactive sessions and are not recommended for programmatic access — use API keys instead.

Authentication errors

Status code	Meaning
401	Missing or invalid API key / token
429	Rate limit exceeded (login endpoint)

End-customer tracking

When making requests on behalf of your own users, pass a customer identifier to attribute usage:

# Via header (works on all endpoints)
curl ... -H "X-Shuttle-Customer-Id: customer_123"

# Via request body (flow execution only)
curl ... -d '{ "customerId": "customer_123", ... }'

PromptShuttle auto-creates customer records on first use. You can manage customers via the Customers API and view per-customer usage in the dashboard.