Authentication - Convexity Infra API

Every Infra API endpoint (except token issuance itself) is protected by an OAuth 2.0 bearer token. You obtain a token by presenting your project API key to Auth-Edge using the client_credentials grant, then send the returned access_token on each subsequent request.

Getting an API key

API keys are issued by the Convexity Infra team — there is no self-service signup yet. Request a key by email with your business details. You’ll receive a test key to integrate against and a live key (sk_live_...) for production traffic.

Request address: to be confirmed — add the infra-admin email here.Treat API keys like passwords: never embed them in client-side code or commit them to source control. If a key is exposed, request a rotation by email immediately.

Present your API key

Call POST /v1/oauth/token with grant_type=client_credentials and your API key.

Receive a short-lived token

Auth-Edge returns an access_token (a signed JWT) and its expires_in lifetime.

Authorize requests

Send Authorization: Bearer <access_token> on every API call until the token expires, then mint a new one.

Obtaining a token

POST /v1/oauth/token The API key can be supplied in either of two RFC 6749-compliant ways:

HTTP Basic (recommended)
Body parameter

Send the key as the username in HTTP Basic auth (Stripe style — empty password):

curl -X POST https://dev.api.withconvexity.com/v1/oauth/token \
  -u "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

Send the key as client_secret in the JSON body:

curl -X POST https://dev.api.withconvexity.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }'

Request body

Field	Type	Required	Description
`grant_type`	`string`	Yes	Must be `client_credentials`.
`client_secret`	`string`	Conditional	Your API key, if not supplied via HTTP Basic auth.
`client_id`	`string`	No	Alternative carrier for the API key (used if `client_secret` is absent).
`audience`	`string`	No	Target service for the token (for example `indexer`). Defaults to the platform’s configured audience.
`scope`	`string`	No	Space-separated scopes to narrow the token (RFC 6749 §3.3), up to 500 chars. Omit for a full-access token.

Response — `200 OK`

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "indexer:read"
}

Field	Type	Description
`access_token`	`string`	Signed JWT to send as a bearer token.
`token_type`	`string`	Always `Bearer`.
`expires_in`	`number`	Token lifetime in seconds (e.g. `600` = 10 minutes).
`scope`	`string`	Granted scope. Omitted for unscoped, full-access tokens.

Token claimsThe JWT encodes your businessId, keyId, the environment (live / test), the granted scope, and an aud (audience). Downstream services read these claims to enforce project context and capabilities — you do not need to send them yourself.

Using the token

Send the access token in the Authorization header on every request:

curl https://dev.api.withconvexity.com/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6..." \
  -H "Accept: application/json"

Token errors

Token issuance returns standard OAuth 2.0 error bodies (RFC 6749 §5.2):

{
  "error": "invalid_client",
  "error_description": "Missing API key. Use HTTP Basic auth or supply client_secret in the body."
}

Status	`error`	Cause
`400`	`invalid_request`	Malformed body or missing `grant_type`.
`401`	`invalid_client`	Missing, malformed, or unrecognized API key.
`403`	`unauthorized_client`	The key is not allowed to mint the requested token.
`503`	`temporarily_unavailable`	The signing/key service is temporarily unavailable.
`500`	`server_error`	Unexpected failure.

Live keys for productionBusiness endpoints reject test tokens with 403 — Test tokens are not allowed, please use your live api key. Mint tokens from your sk_live_... key for production traffic.

Scopes & capabilities

Authorization is layered:

Scopes narrow what a token may do at a coarse level (for example indexer:read).
Capabilities are fine-grained permissions checked per endpoint. The Indexer service, for example, gates each operation on a capability such as indexer.subscribe.evm or indexer.history.read. A token missing the required capability receives 403. Capabilities are granted by the product/plan attached to your project — see Products and Subscriptions.

Rate limiting on the token endpoint is 30 requests per minute per IP.

​Getting an API key

​Obtaining a token

​Request body

​Response — 200 OK

​Using the token

​Token errors

​Scopes & capabilities

Getting an API key

Obtaining a token

Request body

Response — `200 OK`

Using the token

Token errors

Scopes & capabilities