Authentication
Authenticate server requests with scoped Carden keys while keeping human sign-in and Stripe authentication separate.
On this page
Three separate authentication boundaries
| Credential | Where it is used |
|---|---|
| WorkOS AuthKit sign-in | Identifies people using the Carden dashboard or authorized operator area. |
| Carden API key | Authenticates your server's requests to the Carden API for a specific merchant, integration, and environment. |
| Your Stripe credentials | Authenticate your existing backend to Stripe; they are never provided to Carden. |
QuickBooks uses a separate Intuit OAuth consent flow for accounting access. Carden does not use that consent to gain Stripe access, and signing into the dashboard does not create a backend API credential.
Issue and use a key
- Select the intended merchant and environment.
- Open the integration's Keys tab with an account permitted to create keys.
- Create a named key and choose only the allowed scopes your service needs.
- Store the secret in backend secret configuration and send it in the Authorization header.
POST /api/v1/stripe/payment-intent-enrichment HTTP/1.1
Authorization: Bearer <CARDEN_API_KEY>
Content-Type: application/json
Accept: application/jsonSupported scopes
| Scope | Allows |
|---|---|
enrichment:write | Prepare commercial details for Stripe PaymentIntents. |
payments:write | Submit payment reports. |
integrations:read | Read supported integration and sync state. |
integrations:write | Perform supported connection invitation or sync operations. |
Stripe integration keys can grant only enrichment:write and payments:write; QuickBooks integration keys can grant only integrations:read and integrations:write. Create separate provider-specific keys. A valid key with insufficient scope cannot perform an operation, and paused integrations or inactive workspaces cannot use it. Organization and environment are derived from authorization, not from an arbitrary caller-supplied organization field.
Key setup is attached to the selected integration. It requires no caller-entered providerId and no Stripe credential. Rotation is manual: create a replacement key, deploy it, then revoke the old key; an existing secret is not edited in place.
The API currently permits 120 requests per minute per key. Excess requests receive 429. Stripe API error responses include Retry-After: 60; a QuickBooks error envelope may omit that header, so use a minute-scale backoff when it is absent. A rate-limited report remains the same event, not a new payment.
Use different keys for a payment service, webhook handler, and integration management service when their permissions differ. An integration ID or Stripe account ID in a request never expands the key's authority.
Rotation and failures
Create and deploy a replacement key, verify successful calls, then revoke the old credential. For suspected compromise, revoke promptly and investigate recent use. Revocation and a human team-member removal are separate operational checks.
A 401 indicates missing or invalid authentication. A 403 indicates an authenticated request lacks access to the operation or context. Repair the credential or permission rather than continuously retrying with the same key. Retain the response's x-carden-request-id without logging the Authorization header.