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	Admin/user creates	OAuth flow
Lifetime	Until deleted	Idle timeout
MFA	Not applicable	Supported
CSRF	Not required	Required
Revocation	Manual delete	Logout/admin

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

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`	Full automation	All operations

See Roles for detailed permission lists.

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

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

API token management is admin-only:

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
`created_by`	User who created the token
`created_at`	Creation timestamp
`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
Health checks	`viewer`	Read-only sufficient
Emergency restart	`ops`	Only restart, no deploy
Admin automation	`admin`	Full access needed

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
Consider IP allowlisting for sensitive tokens
Use private network access where possible

Audit Logging

All token usage is logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "api_token_id": 42,
  "api_token_name": "ci-production-deploy",
  "method": "POST",
  "path": "/apps/myapp/builds",
  "status_code": 200,
  "rbac_decision": "allow"
}

Token-based requests are distinguishable from session-based requests in audit logs.

Differences from Sessions

No MFA

API tokens don’t support MFA because:

Automation can’t complete interactive MFA
Token role determines permissions
Audit logging provides accountability

For sensitive operations requiring human approval, use Deploy Approvals.

No Expiration

Tokens don’t expire automatically:

Useful for long-running automation
Manual rotation/deletion 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