Skip to content
Rack Gateway

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

Section titled “Base URL”
EnvironmentBase URL
Developmenthttp://localhost:8447/api/v1
Productionhttps://gateway.example.com/api/v1

Authentication

Section titled “Authentication”

Most endpoints require either a session cookie (browser/CLI login) or an API token (automation).

Session Authentication

Section titled “Session Authentication”
Terminal window
# Session cookie name is session_token
curl -b "session_token=YOUR_SESSION_TOKEN" \
  https://gateway.example.com/api/v1/info

API Token Authentication

Section titled “API Token Authentication”
Terminal window
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://gateway.example.com/api/v1/rack-proxy/apps

Endpoint Summary

Section titled “Endpoint Summary”

Health

Section titled “Health”
  • GET /health - Liveness check

OAuth + CLI Login

Section titled “OAuth + CLI Login”
  • POST /auth/cli/start
  • GET /auth/cli/callback
  • POST /auth/cli/complete
  • GET /auth/cli/mfa
  • POST /auth/cli/mfa
  • GET /auth/web/login (also supports HEAD)
  • GET /auth/web/callback
  • GET /auth/web/logout

MFA Management

Section titled “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

Section titled “Admin & Settings”
  • GET /users, POST /users, PUT /users/:email, DELETE /users/:email
  • GET /users/:email/sessions
  • POST /users/:email/sessions/:sessionID/revoke
  • POST /users/:email/sessions/revoke_all
  • POST /users/:email/lock, POST /users/:email/unlock
  • 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 /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 under /integrations/slack/*

Deploy Approvals

Section titled “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

Section titled “Convox Proxy”
  • * /rack-proxy/* (all HTTP methods; CLI-only)
  • GET /convox/* (limited GET-only compatibility)

Error Responses

Section titled “Error Responses”

Errors use a simple JSON payload:

{
  "error": "message"
}

OpenAPI Specification

Section titled “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.