Authentication
Authenticate Carden server requests with provider-scoped keys while keeping human and provider authentication separate.
On this page
Separate authentication boundaries
| Credential | Where it is used |
|---|---|
| WorkOS AuthKit session | Identifies a person using Carden and combines with merchant membership and action permissions. |
| Carden API key | Authenticates one server to one merchant, provider integration, environment, and scope set. |
| Intuit OAuth | Authorizes Carden to access the selected QuickBooks company. |
| Stripe or Square credential | Authenticates the merchant backend to its payment provider and is never provided to Carden. |
QuickBooks consent does not authorize a payment provider. Dashboard sign-in does not create a backend credential. A Carden key cannot be used with Stripe or Square.
Issue and use a key
- Select merchant, provider integration, and environment.
- Open that integration's API keys area with permission to create keys.
- Choose only the scopes required by this service.
- Store the revealed secret in backend secret configuration and send it in Authorization.
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 |
|---|---|
| invoices:read | Read the QuickBooks source explicitly linked to a Stripe or Square destination and authorize source-backed preparation. |
| enrichment:write | Prepare provider context; linked preparation also requires invoices:read. |
| payments:write | Submit immutable Stripe or Square reports with or without preparation. |
| integrations:read | Read supported QuickBooks connection and sync state. |
| integrations:write | Create supported QuickBooks invitations or queue sync work. |
Payment integration keys can grant preparation and reporting scopes. QuickBooks management keys can grant integration scopes. A source link does not merge provider management permissions and existing keys gain no automatic invoices:read.
Linking or issuing source access requires authority over both source and destination in the same merchant and environment. New source-backed preparation also requires a fresh active link, while reports from historical preparation remain independently authorized by the payment integration.
The API currently permits 120 requests per minute per key. A limited request receives 429. Stripe-style errors include Retry-After: 60; QuickBooks management errors may omit it, so use minute-scale bounded backoff when absent.
Rotate and recover
Create and deploy a replacement, verify successful calls and pending outbox events, then revoke the old key. A secret is never edited in place. For suspected compromise, revoke promptly and review recent use, memberships, links, and webhook destinations.
A 401 means authentication is absent or invalid. A 403 means an authenticated key lacks the required provider, context, scope, or active integration. Repair access instead of continuously retrying unchanged.