Authority verification

Applies to: CAAB partner-hosted clients

Endpoint: POST /v1/authority/verify

Last updated: August 2, 2026

Use the CAAB authority verification endpoint when a partner-hosted client receives a short-lived authority envelope and needs CAAB to return only a scoped verification decision.

Initial profile

The generic endpoint supports profile-based verification. The first supported profile is donorops-v2.

Endpoint

Field	Value
Method	POST
URL	https://api.crittoraapis.com/v1/authority/verify
Auth	CaabBrokerCognitoAuth with scope caab/caab.broker.execute
Profile	donorops-v2 is the only initial supported profile

Request body

{
  "profile": "donorops-v2",
  "bindingId": "partner-connection-123",
  "operationId": "donor.create",
  "arguments": {
    "externalDonorId": "donor-456",
    "amount": 2500,
    "currency": "USD"
  },
  "protectedEnvelope": "eyJwcm90ZWN0ZWQiOiJ..."
}

Field	Required	Description
profile	Yes	Authority profile id. Use donorops-v2.
bindingId	Yes	Partner connection binding. Must match the authenticated workload client.
operationId	Yes	Operation being authorized. Must be supported by the selected profile.
arguments	Yes	Operation arguments used to recompute the profile-specific digest.
protectedEnvelope	Yes	Short-lived authority envelope issued by CAAB for verification.

Success response

A successful response confirms that CAAB accepted the profile, verified the signature, matched the signer and binding, validated the digest and lifetime, and reached an allow decision.

{
  "profile": "donorops-v2",
  "bindingId": "partner-connection-123",
  "operationId": "donor.create",
  "decision": "allow",
  "verified": true
}

Verification rules

The request bindingId must match the authenticated workload client's partner connection.
Partner allowlist and headless activation checks follow the current CAAB broker behavior where applicable.
CAAB loads policy crypto credentials through CRITTORA_POLICY_SERVICE_SUB and verifies the protected envelope with Crittora.
The envelope must have a valid signature from the expected signer partner.
Responses never include decrypted plaintext, raw envelope contents, credential values, or raw upstream errors.

DonorOps profile

Profile id is donorops-v2 and supported operations come from DONOROPS_V2_OPERATIONS.
Issuer, audience, binding_id, permission_id, and decision must match the DonorOps authority profile.
Argument digest calculation uses the same canonicalization as DonorOps authority injection.
Envelope lifetime must be within the DonorOps authority lifetime or the profile maximum.

Failure behavior

Status	When returned
400	Malformed body, missing required fields, unknown profile, unsupported operation, or invalid arguments.
403	Binding mismatch, invalid signature, signer mismatch, digest mismatch, expired envelope, or denied decision.
503	CAAB crypto configuration or Crittora verification is unavailable.

Example request

curl -X POST https://api.crittoraapis.com/v1/authority/verify \
  -H "Authorization: Bearer $CRITTORA_WORKLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "profile": "donorops-v2",
  "bindingId": "partner-connection-123",
  "operationId": "donor.create",
  "arguments": {
    "externalDonorId": "donor-456",
    "amount": 2500,
    "currency": "USD"
  },
  "protectedEnvelope": "eyJwcm90ZWN0ZWQiOiJ..."
}'

Related docs

Security model

Bearer token

Scoped decision

CAAB verifies the envelope and returns a decision. It does not return decrypted plaintext, credentials, envelope contents, or raw upstream errors.