API Reference

Rack Gateway exposes a JSON REST API for authentication, admin workflows, and Convox proxying. The OpenAPI spec is the source of truth, but this page summarizes the current surface area.

Base URL

Environment	Base URL
Development	`http://localhost:8447/api/v1`
Production	`https://gateway.example.com/api/v1`

Authentication

Gateway endpoints require a session (browser cookie or CLI login). API tokens (automation) can use the rack proxy (/api/v1/rack-proxy/*) and only four gateway endpoints: GET /info, GET /rack, POST /deploy-approval-requests and GET /deploy-approval-requests/{id}. Every other gateway endpoint returns 403 API tokens cannot use this endpoint.

Each gateway endpoint declares the permission it needs; callers without it get 403 insufficient permissions: requires <permission>. Endpoints under /users/{email} that read or sign out a user’s own sessions, profile or audit log also accept that user themselves.

Session Authentication

The web UI’s session is the session_token cookie; requests that change something also need the CSRF token in an X-CSRF-Token header. A CLI session token is sent as a bearer token:

curl -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  https://gateway.example.com/api/v1/info

API Token Authentication

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://gateway.example.com/api/v1/rack-proxy/apps

Endpoint Summary

Gateway Info

GET /info - the signed-in user, the rack, integration status and the gateway’s version
GET /rack - the rack’s system information (from the rack’s /system)
GET /roles - roles and their permissions
GET /created-by - who created the given apps, builds or releases, for display

Health

GET /health - Health check (503 for a minute after an audit write fails)

CLI login uses the RFC 8252 loopback flow (see OAuth Flow):

POST /auth/cli/start - S256 code challenge, CLI state and loopback redirect_uri; returns auth_url
GET /auth/cli/callback - identity provider redirect; exchanges the code, then binds the browser
GET /auth/cli/mfa - continues the bound browser to MFA (or enrollment)
POST /auth/cli/mfa - submits an MFA code from the bound browser
GET /auth/cli/return - issues the single-use login code and redirects the browser to the CLI’s loopback listener
POST /auth/cli/cancel - cancels the login from the bound browser; returns the loopback URL that tells the CLI
POST /auth/cli/complete - redeems the login code with the CLI’s code verifier for a session token
GET /auth/cli/initiator - the device name and IP that started the login, shown on the approval page
POST /auth/cli/logout - revokes the CLI session sent as the bearer token (cookies are ignored)
GET /auth/web/login (also supports HEAD)
GET /auth/web/callback
POST /auth/web/logout (with the session’s X-CSRF-Token)

MFA Management

All under /auth/mfa:

GET /auth/mfa/status
POST /auth/mfa/enroll/totp/start
POST /auth/mfa/enroll/totp/confirm
POST /auth/mfa/enroll/yubiotp/start
POST /auth/mfa/enroll/webauthn/start
POST /auth/mfa/enroll/webauthn/confirm
POST /auth/mfa/verify
POST /auth/mfa/webauthn/assertion/start
POST /auth/mfa/webauthn/assertion/verify
PUT /auth/mfa/preferred-method
PUT /auth/mfa/methods/:methodID
DELETE /auth/mfa/methods/:methodID
POST /auth/mfa/backup-codes/regenerate
POST /auth/mfa/trusted-devices/trust
DELETE /auth/mfa/trusted-devices/:deviceID

Admin & Settings

GET /users, POST /users, GET /users/:email, PUT /users/:email, DELETE /users/:email
PUT /users/:email/name
GET /users/:email/sessions, GET /users/:email/audit-logs
POST /users/:email/sessions/:sessionID/revoke
POST /users/:email/sessions/revoke_all
POST /users/:email/lock, POST /users/:email/unlock
POST /users/:email/mfa/reset: removes another user’s MFA methods, backup codes and trusted devices and signs them out
GET /api-tokens, GET /api-tokens/:tokenID, POST /api-tokens
PUT /api-tokens/:tokenID, DELETE /api-tokens/:tokenID
GET /api-tokens/permissions
GET /audit-logs, GET /audit-logs/export, GET /audit-logs/verification (the latest hourly verification)
GET /jobs, GET /jobs/:id, DELETE /jobs/:id, POST /jobs/:id/retry
GET /settings
PUT /settings/mfa-configuration, DELETE /settings/mfa-configuration
PUT /settings/allow-destructive-actions, DELETE /settings/allow-destructive-actions
PUT /settings/vcs-and-ci-defaults, DELETE /settings/vcs-and-ci-defaults
PUT /settings/deploy-approvals, DELETE /settings/deploy-approvals
PUT /settings/session-configuration, DELETE /settings/session-configuration
POST /settings/rack-tls-cert/refresh
POST /diagnostics/sentry
Slack integration: GET /integrations/slack, POST /integrations/slack/oauth/authorize, GET /integrations/slack/oauth/callback, PUT /integrations/slack/channels, PUT /integrations/slack/alerts, GET /integrations/slack/channels/list, POST /integrations/slack/test, DELETE /integrations/slack

Apps

GET /apps/:app/env, PUT /apps/:app/env - env values for the web UI (secrets masked unless permitted)
GET /apps/:app/settings
PUT and DELETE on /apps/:app/settings/vcs-ci-deploy, protected-env-vars, secret-env-vars, audit-visible-env-vars, approved-deploy-commands and service-image-patterns

Deploy Approvals

GET /deploy-approval-requests
GET /deploy-approval-requests/:id
GET /deploy-approval-requests/:id/audit-logs
POST /deploy-approval-requests
POST /deploy-approval-requests/:id/approve
POST /deploy-approval-requests/:id/reject
POST /deploy-approval-requests/:id/extend

Convox Proxy

* /rack-proxy/* (all HTTP methods; header authentication only, so the Convox CLI and API tokens, never the browser cookie)
For the web UI, with a session: GET /convox/apps, GET /convox/apps/*, GET /convox/instances, GET /convox/system/processes, PUT /convox/apps/:app/services/:name (scale) and DELETE /convox/apps/:app/processes/:pid

Error Responses

Errors use a simple JSON payload:

{
  "error": "message"
}

OpenAPI Specification

The generated OpenAPI spec is available at:

GET /openapi.json

This schema is generated from the Go handlers and used to build the TypeScript API client.