API Authentication

Authentication MethodCopy Anchor Link

Use a Bearer token in the Authorization header for authenticated API requests. Explicitly public endpoints, such as health checks and published status-page feeds, do not require a token:

curl https://app.supercheck.io/api/jobs \
  -H "Authorization: Bearer sck_live_a1b2c3d4e5f6789012345678901234ab"

Token TypesCopy Anchor Link

CLI TokensCopy Anchor Link

CLI tokens are project-scoped and inherit the creating user's RBAC permissions.

Create a TokenCopy Anchor Link

POST /api/cli-tokens
Authorization: Bearer <existing-token>
Content-Type: application/json

{
  "name": "CI/CD Pipeline",
  "expiresIn": 7776000  // optional, seconds: 3600 (1 hour) to 31536000 (365 days)
}

Response (201):

{
  "success": true,
  "token": {
    "id": "uuid",
    "name": "CI/CD Pipeline",
    "key": "sck_live_a1b2c3d4e5f6789012345678901234ab",
    "start": "sck_live_a1b2...",
    "enabled": true,
    "expiresAt": "2026-04-15T10:30:00Z",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

List TokensCopy Anchor Link

GET /api/cli-tokens
Authorization: Bearer <token>

Enable/Disable a TokenCopy Anchor Link

PATCH /api/cli-tokens/{id}
Authorization: Bearer <token>
Content-Type: application/json

{ "enabled": false }

Revoke a TokenCopy Anchor Link

DELETE /api/cli-tokens/{id}
Authorization: Bearer <token>

Trigger KeysCopy Anchor Link

Trigger keys provide minimal access for CI/CD pipelines — they can only trigger a single job:

POST /api/jobs/{id}/trigger
Authorization: Bearer sck_trigger_f1e2d3c4b5a6789012345678901234cd

Trigger keys cannot access any other API endpoint. Using one on a general endpoint returns 401 Unauthorized. Missing or invalid credentials return 401; a valid token that lacks permission returns 403 Forbidden.

Keep Tokens SecureCopy Anchor Link

• Store tokens in your CI/CD secret manager rather than committing them to source control.
• Use a trigger key when a pipeline only needs to start one job.
• Set an expiry for temporary access and revoke unused tokens.
• Keep no more than 20 CLI tokens per project.
• Tokens stop working when their owner loses organization membership.

Rate LimitingCopy Anchor Link

Request limits depend on the endpoint. The CLI automatically handles 429 responses with exponential backoff.

Rate Limit HeadersCopy Anchor Link

Rate-limited endpoints may include these headers; check for them rather than assuming they are present:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1612137600

When rate limited (429), the Retry-After header indicates how long to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Organization and billing administration, including member management and creating projects, require an interactive browser session. Project-scoped CLI tokens receive 403 for these operations, even when their owner is an organization administrator. Tokens still support scoped organization/project discovery, authentication context, and authorized resource operations within their project.