Making requests

Authentication and scopes

For REST requests under /v1, send your partner API key in the Authorization: Bearer <api-key> header. Create and manage keys in Settings → API Keys in the Aura dashboard. Keep keys on your server and out of browser code, screenshots and logs.

An endpoint can require read, write or admin scope. Check the endpoint's reference before issuing a request. A missing required scope returns 403. Test-prefixed keys are read-only and access your organization's production records. Use the staging base URL for pre-production testing.

GraphQL accepts partner keys and Clerk organization JWTs. A Clerk JWT must contain a user and organization claim. Its organization role controls its permissions. REST partner endpoints require a partner key.

REST pagination

List endpoints return pagination.has_more and pagination.next_cursor. Send the returned cursor unchanged as the next request's cursor parameter. Keep filters the same while traversing a result set. Stop when has_more is false. Check each endpoint for its filters and page-size limits.

curl 'https://api.aura-app.ai/v1/leads?limit=50' \
  -H "Authorization: Bearer $AURA_API_KEY"

# Replace the cursor with pagination.next_cursor from the response.
curl 'https://api.aura-app.ai/v1/leads?limit=50&cursor=RETURNED_CURSOR' \
  -H "Authorization: Bearer $AURA_API_KEY"

See List leads for the response shape. GraphQL uses first, after and pageInfo instead, as described in the GraphQL guide.

Errors and retries

REST errors contain success, error, code and requestId. Save the request ID when asking support to investigate. Treat 400 as invalid input, 401 as missing or invalid authentication, 403 as missing permission, and 404 as a resource that cannot be found within your permitted data.

For 429, wait for the number of seconds in Retry-After before retrying. The Overview describes the current limits. For unsafe writes, check whether the endpoint supports idempotency before automatically retrying: Create payment accepts an Idempotency-Key. GraphQL errors also require checking the response's errors array, as described in its guide.