API Token Management

What API Tokens Are For

API tokens give programmatic access to VersionForge's REST API. You use them to trigger syncs from CI/CD pipelines, query run status from monitoring tools, integrate with external orchestrators, or build custom dashboards. Every API request must include a valid token in the Authorization header.

Creating a Token

1. Navigate to token management

   Go to Settings > API Tokens and click Create Token.

2. Configure the token

   Enter the following:

   • Token name -- A descriptive label (e.g., "CI/CD Pipeline - Production", "Datadog Monitor"). This name appears in audit logs.
   • Scope -- Select the permission level (see Token Scopes below).
   • Expiry -- Choose an expiration period: 30 days, 90 days, 1 year, or custom date. Tokens cannot be created without an expiry.

3. Copy the token

   After creation, the token value is displayed once. Copy it immediately and store it in your organization's secret manager (Vault, AWS Secrets Manager, 1Password, etc.).

   The token value is not stored in VersionForge and cannot be retrieved after you close this dialog. If you lose the token, revoke it and create a new one.

Token Scopes

| Scope | Permissions | Use Case | |-------|------------|----------| | read-only | Query sync runs, connection health, cross-check results, pipeline logs | Monitoring dashboards, observability integrations | | sync-trigger | All read-only permissions + trigger syncs, retry failed runs | CI/CD pipelines, external orchestrators | | admin | All sync-trigger permissions + manage connections, update settings, manage users | Administrative automation, infrastructure-as-code |

Using Tokens with the REST API

Include the token in the Authorization header as a Bearer token:

curl -X GET https://your-instance.versionforge.com/api/v1/sync/runs \
  -H "Authorization: Bearer vf_tok_your_token_here"

All API responses include rate limit headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1712937600

Rate Limiting

Each token is rate-limited independently:

| Scope | Rate Limit | |-------|-----------| | read-only | 120 requests/minute | | sync-trigger | 60 requests/minute | | admin | 30 requests/minute |

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating when the limit resets.

Token Expiry and Rotation

Tokens expire on their configured date. VersionForge sends a warning notification to the tenant admin 14 days before a token expires and again 3 days before.

To rotate a token:

1. Create a new token with the same scope and a fresh expiry.
2. Update your integration to use the new token.
3. Verify the integration works with the new token.
4. Revoke the old token.

This process ensures zero downtime -- the old token remains valid until you explicitly revoke it.

Revoking Tokens

To revoke a token immediately:

1. Navigate to Settings > API Tokens.
2. Find the token by name in the active tokens list.
3. Click Revoke. The token is invalidated immediately -- any in-flight requests using it will fail.

Revoked tokens cannot be reinstated. Create a new token if access is needed again.

Active Tokens Dashboard

The Settings > API Tokens page shows all tokens for your tenant:

| Column | Description | |--------|-------------| | Name | The label you assigned at creation | | Scope | read-only, sync-trigger, or admin | | Created | Date the token was created and by which user | | Expires | Expiration date with a warning badge if within 14 days | | Last used | Timestamp of the most recent API call using this token | | Status | Active or Revoked |

Best Practices

• Rotate quarterly -- Set token expiry to 90 days and rotate before expiry as part of your regular security cadence.
• One token per integration -- Do not share tokens across systems. Separate tokens make it easy to revoke access for one integration without disrupting others.
• Never embed in client-side code -- API tokens should only be used in server-side environments, CI/CD secrets, or secret managers. If a token is exposed in a browser, mobile app, or public repository, revoke it immediately.
• Monitor the "Last used" column -- Tokens that have not been used in 30+ days may indicate abandoned integrations. Revoke them to reduce your attack surface.
• Use read-only by default -- Start with the most restrictive scope and upgrade only when the integration genuinely requires more permissions.