Authentication

Carrot API uses OAuth 2.0 client credentials with bearer tokens. There is no user login step. Integrations authenticate with a clientId and clientSecret.

Authentication flow

1. Receive clientId and clientSecret from the Carrot API team.
2. Request an access token from the auth endpoint using Basic Authentication.
3. Use the returned bearer token in the Authorization header on API requests.

curl --request POST \
  --url https://auth.api.carrot.eco/oauth2/token \
  --header 'Authorization: Basic <clientId:clientSecret in base64>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api.carrot.eco/main-scope'

Token lifecycle

• access_token maximum duration is currently 1 hour.
• expires_in is returned by the token endpoint response and must be treated as API-provided runtime data (not hard-coded in your integration).
• Refresh tokens are not used in this flow.
• Request a new token before expiry to avoid request failures.

Token response format

Typical successful response:

{
  "access_token": "<jwt-or-opaque-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.carrot.eco/main-scope"
}

Applying bearer tokens

Send your token on each request:

Authorization: Bearer <access_token>

Environment behavior

Environment is controlled by credentials, not by URL.

• Test credentials operate only on test data.
• Production credentials operate only on production data.
• A test token cannot modify production documents, and the reverse is also true.

See Environments for operational guidance.

Common auth errors

• 401 unauthorized: invalid, expired, or malformed bearer token.
• 403 restrictedResource: valid token without permission for the target resource.

Environments · Quick Start · Error Handling