Skip to content

Authentication

The API has two ways in. The one you use depends on what you are building.

The application API under /api/v1 authenticates with a bearer token in the Authorization header:

Authorization: Bearer <access_token>

Get the token by signing in with POST /api/v1/auth/login (email and password). The response carries access_token, refresh_token and access_token_expires_in in seconds. An account with multi-factor authentication gets a challenge back instead, and finishes with POST /api/v1/auth/mfa/verify-challenge.

  • The access token is short-lived (30 minutes). Renew it with POST /api/v1/auth/refresh and the refresh token, which lasts seven days. Each refresh returns a new pair.
  • A refresh token cannot be used as an access token, and an access token cannot be used to refresh.
  • The browser app uses the same token in an HttpOnly cookie.
  • Login is limited to 5 attempts a minute. After 10 failed attempts, that email from that address is locked out for 15 minutes, and the response is a 429 with a Retry-After header.

Keep tokens secret. Treat them like passwords.

The read-only public API under /api/v1/public/v1 (contract search and detail, and webhook registration) authenticates with an API key, not a token:

X-API-Key: gcap_<key>

Create a key from API Keys inside the application. The full key is shown once, when you create it, and only a hash is stored. Revoke a key from the same page.

  • A request with no X-API-Key header gets 401.
  • A key that is invalid or revoked gets 403.
  • Public API keys are limited per key. See Rate Limits.
  • 401 Unauthorized: missing, expired, or invalid token or key.
  • 403 Forbidden: valid credentials, but your role does not permit this action.
  • 429 Too Many Requests: rate limited. The response includes a Retry-After header telling you how long to wait.

Try this in the platform