API Tokens

API tokens provide authentication for automated systems like CI/CD pipelines, scripts, and integrations. Unlike sessions, tokens are long-lived and don’t require interactive login.

Token vs Session Authentication

Aspect	API Tokens	Sessions
Use Case	Automation, CI/CD	Human users
Creation	Deployers (for themselves) or admins	OAuth flow
Lifetime	Until deleted or the optional `expires_at`	Web: idle timeout; CLI: 90 days from last use
MFA	Not applicable	Supported
CSRF	Not required	Required
Revocation	Manual delete	Logout (web or `rack-gateway logout`), or revoking it from the user’s sessions

Token Anatomy

Each API token consists of:

Format: rgw_<random>

Example: rgw_kX7mN2pQ9rT4wY8zA1bC3dE5fG...=
         ^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^
         prefix random component

Component	Description
`rgw_`	Rack Gateway token prefix
Random	32 bytes, base64url encoded (with padding)

Token Storage

Like session tokens, API tokens are hashed before storage:

Client has:  rgw_kX7mN2pQ9rT4wY8...
Database:    SHA-256 hash of full token

Token Roles

API tokens store explicit permissions. Roles are a shortcut at creation time:

Role	Use Case	Permissions
`viewer`	Monitoring	Read-only access
`ops`	Emergency scripts	Restart, exec, view env
`deployer`	Deploy automation	Full deploy capabilities
`cicd`	CI/CD pipelines	Minimal deploy + approval
`admin`	Rack automation	All Convox operations, capped by the owner’s role

See Roles for detailed permission lists.

What a Token Can Do

A token is always limited by the person who owns it:

Capped by the owner’s current role. Every request needs the permission in the token’s own list and in the owner’s current role. Demote the owner and their tokens lose the extra access on the next request.
Stops working with its owner. Tokens of a locked or deleted user are rejected.
Created within the owner’s role. When a token is created or edited, each permission must be one the owner’s role grants. Deployers can create tokens for themselves; only admins can create tokens for other users.
Rack access only, plus a few gateway endpoints. Tokens can use the rack proxy (/api/v1/rack-proxy/*) and only these gateway endpoints: GET /api/v1/info, GET /api/v1/rack, POST /api/v1/deploy-approval-requests and GET /api/v1/deploy-approval-requests/:id. User, token, settings, audit-log and approval endpoints refuse tokens, even admin-owned ones.
No privileged runs. Tokens can never start a process with a custom image, host volumes, privileged mode or node placement options.

Creating Tokens

Web UI

Navigate to API Tokens in the sidebar
Click Create Token
Enter a descriptive name (e.g., ci-production-deploy)
Select the appropriate role
Click Create
Copy the token immediately - it won’t be shown again

CLI

# Create a CI/CD token
rack-gateway api-token create --name "GitHub Actions" --role cicd

# Create a viewer token for monitoring
rack-gateway api-token create --name "Datadog Monitor" --role viewer

Using Tokens

CLI Usage

# Set token as environment variable
export RACK_GATEWAY_API_TOKEN=rgw_kX7mN2pQ9rT4...

# Or use --api-token flag
rack-gateway apps --api-token rgw_kX7mN2pQ9rT4...

HTTP API Usage

Include the token in the Authorization header:

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

CI/CD Integration

These examples deploy straight away, which needs a token with the deploy permissions themselves. A cicd token deploys only with an approved deploy approval: request one first (rack-gateway deploy-approval request --wait).

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          RACK_GATEWAY_API_TOKEN: ${{ secrets.RACK_GATEWAY_API_TOKEN }}
        run: |
          rack-gateway deploy -a myapp

Store the token in GitHub Secrets (Settings → Secrets and variables → Actions).

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: Deploy
          command: rack-gateway deploy -a myapp
          environment:
            RACK_GATEWAY_API_TOKEN: ${RACK_GATEWAY_API_TOKEN}

Store the token in CircleCI Environment Variables (Project Settings → Environment Variables).

deploy:
  stage: deploy
  script:
    - rack-gateway deploy -a myapp
  variables:
    RACK_GATEWAY_API_TOKEN: $RACK_GATEWAY_API_TOKEN

Store the token in GitLab CI/CD Variables (Settings → CI/CD → Variables).

Token Management

Listing Tokens

Users with gateway:api_token:read (every role) see their own tokens; admins see everyone’s:

rack-gateway api-token list

Revoking Tokens

# Revoke by ID
rack-gateway api-token delete <token-id>

Or through the web UI: API Tokens → Select Token → Delete

Token Metadata

Each token tracks:

Field	Description
`name`	Descriptive identifier
`permissions`	Explicit permissions on the token
`user`	The owner, whose role caps the token
`created_by`	User who created the token (an admin can create one for another user)
`created_at`	Creation timestamp
`expires_at`	Optional expiry
`last_used_at`	Last successful use

Security Best Practices

Token Naming

Use descriptive names that indicate:

Purpose: ci-production-deploy
Environment: staging-monitoring
System: github-actions-main

Bad examples: token1, test, my-token

Role Selection

Always use the minimum required role:

System	Recommended Role	Reason
CI/CD deploy	`cicd`	Minimal scope + approvals
Monitoring	`viewer`	Read-only sufficient
Emergency restart	`ops`	Only restart, no deploy
Rack automation	`admin`	Only if it really needs every Convox operation

Token Rotation

Rotate tokens periodically:

Create new token with same role
Update all systems using old token
Verify systems work with new token
Delete old token

Recommended rotation frequency:

Production tokens: Quarterly
CI/CD tokens: Every 6 months
Development tokens: Annually

Monitoring Usage

Review token usage regularly:

Tokens not used in 90+ days should be reviewed
Unexpected usage patterns may indicate compromise
Failed authentication attempts are logged

Token Security Considerations

Storage

Never commit tokens to git
Use secrets management (AWS Secrets Manager, Vault, etc.)
Environment variables are preferred over config files
CI/CD systems have secure secret storage

Exposure

If a token is exposed:

Delete immediately

Web UI → API Tokens → Delete token
Review audit logs

Check what actions were taken with the token
Create replacement

Generate new token with same role
Update systems

Deploy new token to affected systems
Investigate

Determine how exposure occurred

Network Security

Tokens should only be used over HTTPS
Tokens have no IP allowlist, so keep the gateway on a private network (CI runners reach it through Tailscale or a VPN)

Audit Logging

All token usage is logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "user_email": "deployer@example.com",
  "api_token_id": 42,
  "api_token_name": "ci-production-deploy",
  "action_type": "convox",
  "action": "build.create",
  "resource": "myapp",
  "status": "success",
  "rbac_decision": "allow",
  "http_status": 200
}

Token requests carry api_token_id and api_token_name, and user_email is the token’s owner.

Differences from Sessions

No MFA

API tokens don’t support MFA because:

Automation can’t complete interactive MFA
The token’s permissions, capped by its owner’s role, determine access
Audit logging provides accountability

For sensitive operations requiring human approval, use Deploy Approvals.

Optional Expiration

Tokens don’t expire unless you set expires_at when creating them (for example rack-gateway api-token create --expires-at 2027-01-01T00:00:00Z):

Without an expiry, tokens suit long-running automation
Manual rotation/deletion is still required
Regular review process recommended

No CSRF

Tokens are passed in headers, not cookies:

Not vulnerable to CSRF attacks
No CSRF token required
Bearer token auth is inherently CSRF-safe

Next Steps

Roles - Role definitions for tokens
Deploy Approvals - Human approval for CI/CD
Audit Trail - Token activity logging