Skip to main content

​
Authentication & API access

Use this page when integrating HTTP clients, scripts, or WebSocket clients with the Gateways API. Endpoint-level request and response bodies are documented on API documentation and the numbered topic pages in this tab.

​
Base URL

https://api.gateways.app
Use your deployment’s host if you self-host the API.

​
Summary of credential types

MethodWhen to useHow you send it
Session JWTInteractive apps, first-party clients after loginAuthorization: Bearer <session_token>
API keyAutomation, CI, integrations without a browser sessionX-API-Key: sk_... or Authorization: Bearer sk_...
URL / WebSocket tokenTerminal, IDE, or other WebSocket upgrades?token=<session_jwt> on the WebSocket URL, or Authorization: Bearer, or Sec-WebSocket-Protocol (see below)
  • Session tokens are JWTs returned by POST /api/auth/login, POST /api/auth/signup, POST /api/auth/login/verify-2fa, and OAuth success redirects. They are tied to an active row in sessions (invalidated on logout or expiry).
  • API keys are opaque secrets prefixed with sk_, created in account settings via the API below. The server stores only a SHA-256 hash; the full secret is shown once at creation.

​
Session JWT (Bearer)

After a successful login or signup, responses include data.token (and often refreshToken for the product UI). Send the access token on every request: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Two-factor (2FA): If login returns requires2FA: true, complete POST /api/auth/login/verify-2fa before using the session token. See Authentication & user management. Errors: 401 typically means missing token, expired session, or revoked session—log in again.

​
API keys (sk_…)

API keys authenticate as your user without a browser session. They are intended for non-admin project and resource APIs.

​
Create, list, and revoke

Management endpoints require a normal session JWT (password or SSO login)—not an API key. The backend rejects key management when the active credential is an API key (403).
MethodPathDescription
GET/api/users/api-keysList active keys (metadata only: id, name, prefix, dates).
POST/api/users/api-keysCreate a key. Body: { "name": "optional label" } (string, max 128 chars). Returns the secret once in data.secret.
DELETE/api/users/api-keys/:idRevoke a key by database id.
Limits: You can have at most 10 active keys per user. Creating an 11th returns 429 with maxKeys. Create response (201): 
{
  "message": "Store this key securely; it will not be shown again.",
  "data": {
    "id": 123,
    "name": "CI deploy",
    "keyPrefix": "sk_a1b2c3d4e5",
    "secret": "sk_……………………………………………………"
  }
}

​
Using an API key on requests

Send the raw secret (the full string starting with sk_) using either: 
X-API-Key: sk_……………………………………………………
or 
Authorization: Bearer sk_……………………………………………………
The server detects sk_ in the Bearer value and resolves the key by hash. Do not send a session JWT and an API key in conflicting ways—use one credential per request. Last used: Successful key auth updates last_used_at for that key (best-effort).

​
Restrictions for API keys

  • Platform administration routes — Forbidden (403) for API keys. They require a browser-style session JWT and operator privileges; they are not documented in this reference.
  • Creating or revoking API keys — Only with session JWT (GET/POST/DELETE /api/users/api-keys), not with another API key.
All other authenticated routes that accept a session JWT generally accept an API key unless your deployment adds extra middleware.

​
WebSocket and URL authentication

WebSocket upgrades (for example terminal or IDE services) authenticate the same session JWT as HTTP, but browsers and proxies often pass the token outside the Authorization header. Supported patterns (as implemented in the WebSocket auth helper):
  1. Query string: wss://host/path?token=<session_jwt>
  2. Header: Authorization: Bearer <session_jwt>
  3. Subprotocol: first value in Sec-WebSocket-Protocol may carry the token
The server verifies the JWT and checks that the token is still an active session in the database, then allows the upgrade. Note: API key secrets (sk_…) are for HTTP API key auth; WebSocket flows in the product typically use the session JWT from login.

​
Choosing JWT vs API key

ScenarioRecommendation
User logged into the appSession JWT
Scripts, Terraform, cron jobsAPI key
Operator dashboardsSession JWT with appropriate role
Public webhooksNot covered here—use server-side verification of your own design