Authentication¶

Service Accounts use a two-step authentication model: exchange credentials for a session token, then use that token as a Bearer token on all subsequent API calls.

Obtaining a Session Token¶

POST /api/v1/service-account/auth
Content-Type: application/json

Request body:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "client_id": "svc_abc123def456ghi789jkl012mno345pq",
  "client_secret": "your-64-char-secret-here"
}

Field	Required	Description
`uuid`	Yes	The account's UUID (shown at creation and in the management UI)
`client_id`	Yes	The `svc_`-prefixed client identifier
`client_secret`	Yes	The plaintext secret (shown once at creation or regeneration)

Success response (200 OK):

{
  "success": true,
  "service_account": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "CI/CD Pipeline Account",
    "scopes": ["read", "write"]
  },
  "session": {
    "token": "64-char-alphanumeric-session-token",
    "token_type": "Bearer",
    "expires_at": "2026-03-25T10:00:00+00:00",
    "expires_in": 86400
  }
}

Session tokens are valid for 24 hours. Use the returned token as a Bearer token on all subsequent API calls:

Authorization: Bearer <session_token>

Authentication Errors¶

HTTP	Code	Condition
`422`	`VALIDATION_ERROR`	Missing or malformed request fields
`401`	`INVALID_CREDENTIALS`	UUID not found, `client_id` mismatch, or incorrect secret
`401`	`SERVICE_ACCOUNT_INACTIVE`	Account status is inactive
`401`	`SERVICE_ACCOUNT_EXPIRED`	Account's expiry date has passed
`401`	`IP_NOT_ALLOWED`	Requesting IP is not in the configured allowlist

To avoid disclosing which field failed, UUID lookup failures and credential mismatches both return INVALID_CREDENTIALS. Check all three values if authentication fails unexpectedly.

Verifying a Session¶

GET /api/v1/service-account/auth/verify
Authorization: Bearer <session_token>

Returns the current session state and confirms the service account is still active. Use this endpoint to check whether a cached token is still valid before making API calls.

If the account has been deactivated or deleted after the session was created, the session is immediately invalidated and 401 SERVICE_ACCOUNT_INACTIVE is returned.

Revoking a Session¶

POST /api/v1/service-account/auth/revoke
Authorization: Bearer <session_token>

Immediately invalidates the session token. Call this endpoint at the end of a pipeline run or automated job to limit the window of exposure for the token.

Session Lifecycle¶

Credentials → POST /auth → Session token (24h TTL)
                                  ↓
                    Use as Bearer token on API calls
                                  ↓
                    POST /auth/revoke (optional, ends session early)

Sessions are stored server-side. The token itself contains no claims — its validity is verified on each request against the server-side session store. If the service account is disabled or deleted, all of its sessions are invalidated immediately regardless of their remaining TTL.