Authorization and API integration

Allow only when every condition is met

Check the authenticated actor and tenant, requested action, record, and grant validity. Deny by default when required conditions are missing.

Actor

The authenticated service or partner. Do not trust client_id in the request body.

Record

Restrict records to the authenticated tenant_id.

Action and purpose

Check permissions such as shipping.address.read and their associated delivery purpose.

Additional conditions

Check audience, expiry, revocation, usage count, and relationship to the person.

Consistent decisions

Account for state changes between authorization, retrieval, and usage-count updates.

Service authentication and credentials

Use Microsoft Entra application Bearer tokens. Use Managed Identity on Azure, or authenticate an application with its certificate private key to obtain a token. This is not mTLS transport authentication. The current Vault trusts one Entra directory; another organization's identity is not automatically supported. Keep credentials on the backend.

Audience restrictions

Validate token audience and destination. Reject tokens issued for another API.

Credential rotation

Manage retirement of old credentials and the transition window.

Separate browser and server credentials

Never embed server credentials in JavaScript or HTML.

Errors, retries, and audit

Record denial reasons internally without revealing other tenants' records or personal data. When a timeout leaves the result uncertain, use idempotency keys or status queries rather than blindly retrying.

401 / 403

Distinguish missing authentication from missing authorization. Record details in protected internal logs.

404

Consider indistinguishable responses for missing and unauthorized records.

409 / 429

Idempotency conflicts and rate limits. Define retry policy and waiting periods.

503

If permission or revocation state cannot be checked, stop rather than treating the request as authorized.

DATA / INTEGRATION EXAMPLE

Data and integration example

These samples explain the design. Field names and values are illustrative, not an executable API reference.

{
  "operation": "Authorization inputs and decision example",
  "authenticated_context": {
    "tenant_id": "tenant_a",
    "client_id": "carrier-a"
  },
  "request": {
    "action": "shipping.address.read",
    "resource_ref": "order_example_01",
    "purpose": "fulfillment"
  },
  "decision": {
    "allowed": true,
    "fields": [
      "postal_code",
      "address",
      "recipient_name"
    ],
    "decision_id": "dec_example_01"
  }
}

Build authentication context from verified credentials. Never use a client-supplied tenant_id as authority.

Related technical designs

Integration designed for your workflows.

Map retained data, partners, and required actions to identify ways to reduce exposure.