CAAB headless operator runbook
Use this runbook to provision the per-environment Crittora Secure identity used by platform_service_v2, validate same-partner decrypt continuity, activate individual headless bindings, rotate credentials, and roll back safely.
Provision the policy-crypto identity
Environment provisioning
- Create a dedicated partner through the supported Crittora Secure partner-provisioning service. Do not write directly to Crittora tables.
- Create one unique app client under that partner with exactly sign, encrypt, decrypt, and verify (s/e/d/v).
- Store the five credential fields in a CAAB-owned Secrets Manager secret using schema caab.policy-crypto.v1.
- Configure CAAB with the service sub, Crittora recipient partner ID, and secret ARN.
- Create a replacement app client under the same Secure partner before enabling v2 writes.
1{
2 "schema_version": "caab.policy-crypto.v1",
3 "environment": "production",
4 "slot": "primary",
5 "service_sub": "<crittora-app-client-sub>",
6 "partner_id": "<crittora-secure-partner-id>",
7 "permissions": ["s", "e", "d", "v"],
8 "credentials": {
9 "username": "<write-only>",
10 "password": "<write-only>",
11 "api_key": "<write-only>",
12 "access_key": "<write-only>",
13 "secret_key": "<write-only>"
14 }
15}Call the Crittora Secure Managed API
Use https://managed.crittoraapis.com as the base URL. The client appends the endpoint path; do not insert /v1.
Sign and encrypt
1POST https://managed.crittoraapis.com/sign-encrypt
2<five Crittora credential headers>
3Content-Type: application/json
4
5{"data":"<canonical-policy-json>"}For platform_service_v2, omit the optional recipient permissions list. The authenticated app client's Crittora Secure partner is the recipient.
Decrypt and verify
1POST https://managed.crittoraapis.com/decrypt-verify
2<five Crittora credential headers>
3Content-Type: application/json
4
5{"encrypted_data":"<ciphertext>"}Normalize both direct JSON responses and API Gateway-style envelopes whose body is either a JSON string or object.
Validate before enabling v2 writes
Required proof
- Use the primary identity to sign/encrypt a canonical test policy and decrypt/verify the result.
- Use the replacement identity to decrypt ciphertext produced by the primary identity.
- Use the replacement identity to produce and decrypt a new ciphertext.
- Confirm direct JSON and API Gateway response envelopes are both normalized correctly.
- Run focused policy-crypto, partner-experience, and signed-context verification tests.
Activate a partner binding
Activation succeeds only when every applicable gate is open. A least-privilege Cognito client_credentials workload client is the onboarding model for new production bindings; the legacy all-scope pilot client is compatibility-only.
| Gate | Required check |
|---|---|
| Environment feature | Headless Partner API flag is enabled for the environment. |
| Allowlist | The binding is present when an environment allowlist is configured. |
| Connection | Partner connection is active and mapped to the expected CAAB partner and binding. |
| OIDC | External OIDC profile is active and issuer/audience/tenant checks are correct. |
| Binding activation | The binding-level headless activation flag is enabled. |
| Workload mapping | The presented workload client is active and maps to this binding. |
| Route scope | The client has the granular OAuth scope required by the route. |
Use POST /admin/partner-connections, GET /admin/partner-connections/{bindingId}, POST .../workload-clients, DELETE .../workload-clients/{clientId}, and PUT .../headless-activation for workload administration. A creation response is the only response that contains the Cognito client secret.
Rotate the policy-crypto credential
Create the replacement SEDV app client under the same Crittora Secure partner.
Prove it can decrypt existing ciphertext written by the primary identity.
Change the deployed service subject and secret reference.
Verify new writes, old-policy decrypts, governed invocations, audit, metering, and diagnostics.
Revoke the former credential only after telemetry remains clean.
Roll back headless access
Disable the binding-level headless activation first. This immediately rejects new headless requests while preserving subjects, mappings, policies, APIs, downstream credentials, experience configuration, audit evidence, and all legacy data.
When revoking a workload client, CAAB removes its server-side mapping before deleting the Cognito client. If Cognito cleanup fails, the missing mapping still causes requests to fail closed.
Troubleshoot provisioning and invocation
| Symptom | Meaning and corrective action |
|---|---|
| Partner not found | A CAAB partner ID may have been supplied where a Crittora Secure partner ID is required. Locate or provision the Secure partner through the supported service. |
| UsernameExistsException | The requested app-client username already exists. Choose a unique service identity name and inspect the provisioning Lambda logs. |
| Managed API 404 | Use https://managed.crittoraapis.com and append /sign-encrypt or /decrypt-verify. Do not use /v1. |
| Replacement cannot decrypt | Confirm both app clients belong to the same Secure partner, both have s/e/d/v, and CAAB reads the intended secret version. Do not revoke the primary. |
| User assertion rejected | Confirm it is an access token and that issuer, audience, expiry, token_use, and tenant/group claim match the active OIDC profile. |
| Cross-binding request denied | Expected behavior. The route binding must match the workload client's server-side mapping. |
Crittora CAAB
Govern which operations an AI agent, user, or API client can invoke, with signed policy integrity and runtime enforcement.