Authentication
The API has two ways in. The one you use depends on what you are building.
Signed-in API: bearer token
Section titled “Signed-in API: bearer token”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/refreshand 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
429with aRetry-Afterheader.
Keep tokens secret. Treat them like passwords.
Public API: API key
Section titled “Public API: API key”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-Keyheader gets401. - A key that is invalid or revoked gets
403. - Public API keys are limited per key. See Rate Limits.
Errors
Section titled “Errors”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 aRetry-Afterheader telling you how long to wait.
Related
Section titled “Related”Try this in the platform