Purpose-scoped tokens and revocation

Keep personal data out of tokens

An example uses unpredictable opaque tokens with server-side scope and expiry. Require the recipient's authentication in addition to the token to limit theft impact.

token_hash

A lookup value for matching tokens. Keep raw tokens out of logs and ordinary admin screens.

audience

The authorized recipient. Reject use by a different integration partner.

scope / purpose

Permitted data and purpose. Do not default to broad grants.

resource_ref

The order or delivery record. Prevent use for another record.

expires_at / remaining_uses

Expiry and usage limit. Reject expired and consumed tokens server-side.

Single use and lost responses

A proxy ID references a stored address. A delivery token adds conditions for an approved application to retrieve permitted fields for a particular order. Protect both. A successful retrieval consumes a single-use token; replay of the same response is not guaranteed. If a response is lost, check order and processing state before deciding to issue another token.

Expiry, revocation, and changes

Register a new address instead of editing one in place. Inspect the current binding, pass its Version as expectedVersion, change the order and issue a token for the new version. Changing the order version blocks all older-version tokens. Additional issuance at the same version does not revoke existing tokens. Check other orders and retention requirements before deleting an old address. Plaintext already retrieved cannot be recalled.

State transitions

active → consumed / expired / revoked. Never reactivate a revoked state.

Caching

Limit revocation lag. High-risk operations must verify authoritative state.

Limits

Revocation cannot recover personal data already retrieved by a partner.

DATA / INTEGRATION EXAMPLE

Data and integration example

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

{
  "operation": "Delivery token issuance example",
  "request": {
    "proxy_id": "nym_example_01",
    "resource_ref": "order_example_01",
    "audience": "carrier-a",
    "scope": [
      "shipping.address.read"
    ],
    "expires_in_seconds": 600,
    "max_uses": 1
  },
  "response": {
    "token": "tok_example_not_a_real_token",
    "expires_in_seconds": 600
  }
}

600 seconds and one use are examples. A signed JWT alone does not ensure early revocation or single use; additional state management is needed.

Related technical designs

Integration designed for your workflows.

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