CAAB headless Partner API
The Partner API lets a partner-hosted application or MCP server automate the supported CAAB administration and governed invocation lifecycle for one binding. CAAB still owns identity mapping, policy protection, authorization, downstream credential injection, audit, and quota enforcement.
Availability and scope
The Partner API is additive. It does not replace the CAAB portal, hosted MCP URLs, or Cognito-backed subjects. A partner workload can register external subjects, import and version API specifications, store write-only downstream authentication, manage templates and permission boundaries, configure the partner experience, invoke governed operations, and read audit, usage, metering, and diagnostic evidence.
Identity and namespace model
| Identity | Owner | Credential location | Purpose |
|---|---|---|---|
| Policy-crypto service identity | CAAB | CAAB Secrets Manager | Crittora Secure sign/encrypt and decrypt/verify for v2 policies. |
| Partner workload identity | CAAB-issued per binding | Partner server secret manager | Authenticate management and governed API calls. |
| Partner end-user identity | Partner | Partner OIDC provider/session | Identify the human initiating an invocation. |
| CAAB authorization subject | CAAB | Credential-free persistence record | Bind the external identity to templates and policies. |
| Legacy CAAB subject identity | CAAB | Existing legacy store | Preserve v1 policy decrypt behavior. |
Authenticate a governed invocation
Every governed invocation uses two bearer credentials with different purposes. The Authorization token identifies one workload client, CAAB partner, and binding. The X-CAAB-User-Assertion identifies the partner end user.
1POST /v1/bindings/bnd_01JZ/invoke
2Authorization: Bearer <binding-scoped-workload-access-token>
3X-CAAB-User-Assertion: <partner-issued-user-access-token>
4Idempotency-Key: 8f5622c4-2fa5-493f-924f-e9d9f2ed2bea
5Content-Type: application/json
6
7{
8 "apiId": "orders-api",
9 "permissionId": "orders-api:post:/orders/{orderId}/refund",
10 "arguments": {
11 "path": { "orderId": "ord_123" },
12 "body": { "amount": 2500 }
13 }
14}Use a short-lived partner-issued access token for the user assertion, not an ID token.
CAAB validates asymmetric signature, allowed algorithm,
kid, issuer, audience/client ID,exp,iat, tenant claim,token_use=access, and immutable subject.CAAB derives the authorization subject from the binding, issuer, and external subject. A caller cannot select a CAAB subject ID.
A workload client cannot cross bindings even when the same partner owns both bindings.
Recommended onboarding order
Set up one binding
- Exchange the workload client secret once, then store it in the partner server's secret manager.
- Configure and activate the binding's external OIDC profile.
- Register external subjects and confirm issuer, tenant, and immutable subject mappings.
- Import or preview an OpenAPI definition and activate the reviewed revision.
- Create write-only downstream auth profiles; verify that reads return metadata and presence indicators only.
- Create templates and assign least-privilege permission boundaries to external subjects.
- Configure branding, communications, experience profile, MCP URL, and webhooks as needed.
- Enable headless activation only after allowed and denied invocation tests succeed.
Binding-scoped API surface
All public resources are scoped beneath /v1/bindings/{bindingId}. The binding in the route must match the workload token's server-side mapping.
| Resource group | Purpose |
|---|---|
| /external-subjects/{externalSubject} | Register, read, update, and deactivate external identities. |
| /subjects/{externalSubject}/permission-boundary | Read, assign, version, and remove subject authority. |
| /apis and /apis/preview | Preview/import specifications and manage API revisions and activation. |
| /auth-profiles/{apiId}/{profileId} | Configure write-only downstream static or OAuth authentication. |
| /permission-boundary-templates | Create and manage reusable least-privilege templates. |
| /branding, /communications, /experience-profile | Manage the partner-controlled headless experience. |
| /webhooks | Manage event recipients and recipient verification material. |
| /invoke | Invoke one operation after user assertion and policy verification. |
| /audit, /usage, /metering, /diagnostics | Read operational, authorization, and consumption evidence. |
See the Partner API reference for methods, deployed Cognito scopes, parameters, and schemas. The YAML is served at /openapi/caab-partner-api-v1.yaml and can be refreshed from the CAAB source contract with npm run sync:caab-openapi.
Request and response controls
| Control | Required behavior |
|---|---|
| OAuth scopes | Each workload client receives only the granular deployed Cognito scopes it needs, such as caab/caab.partner.subjects.read, caab/caab.permission-boundary.instantiate, and caab/caab.broker.execute. |
| Idempotency-Key | Send a unique key for every mutation so a safe retry cannot create duplicate state. |
| If-Match | Send the current entity version when changing a versioned resource. A stale version is rejected. |
| Pagination | Treat cursors as opaque; do not construct or interpret them. |
| Rate limits | Honor rate-limit headers and retry only after the indicated interval. |
| Secrets | Secret values are accepted on writes only and never returned by a later read. |
| Errors | Use the standardized error code, message, request ID, and field details for handling and support. |
Responsibility and secret boundaries
| Owner | Responsibility |
|---|---|
| CAAB | Policy crypto, workload provisioning/revocation, OIDC validation, external-subject mapping, policy-context verification, authorization, audit, quotas, rollback, and encrypted downstream credential injection. |
| Partner | End-user identity and recovery, MCP authentication, API definitions, downstream OAuth/security configuration, branded experience, webhook recipient keys, and secure storage of the workload client secret. |
Compatibility guarantees
Existing portal routes, public payloads, Cognito pools, hosted MCP URLs, invitations, recovery, notifications, credential bundles, and v1 policy decrypt remain active.
A missing identity mode resolves to
caab_cognito; a missing crypto version resolves tosubject_credentials_v1.External OIDC activation is per binding and can coexist with legacy Cognito subjects.
Deployment does not rewrite or re-encrypt legacy records.
Rollback disables new headless requests without deleting either legacy or headless data.
Next: complete a sandbox governed invocation with the Partner API
Crittora CAAB
Govern which operations an AI agent, user, or API client can invoke, with signed policy integrity and runtime enforcement.