Send REST requests with custom headers, a JSON body, and an Authorization: Bearer … credential.
Using AddressMask for yourself? Compare personal plans and explore AddressMask+
REST API · v1 · United StatesIntegrate AddressMask.
A platform-independent guide to collecting an AddressMask, requesting consumer permission, creating a delivery-bound token, resolving the approved result, and processing signed events.
The endpoint reference below is projected from capabilities enabled for this deployment. Examples describe the authorization model; they do not claim that a gated operation is currently available.
Any HTTPS-capable system can integrate.
Your application can be custom code, an automation platform, a commerce backend, or another integration runtime. Product names and programming languages do not matter; the security boundary does. All protected calls must run server-to-server.
Keep API keys and webhook secrets in an encrypted credential store. Never expose them to a page, form, mobile bundle, log, or analytics event.
Persist the permission, policy, delivery, token metadata, and request IDs needed to resume safely after a timeout or process restart.
Recommended for asynchronous status changes. The receiver must access the unmodified request body and calculate HMAC-SHA256.
Set up the AddressMask side
Organization, client, key, and webhook creation happen in the signed-in business workspace. Record IDs as configuration and credentials as secrets.
- Create or select an organization
In the business workspace, use the organization picker at the top. Add a new organization if needed, then select it before configuring integrations.
- Create separate API clients
Open API clients & keys. Create a Merchant client for permission requests and token issuance. Create a separate eligible resolver client for the service that will receive address results; a Merchant client cannot resolve tokens.
- Issue least-privilege keys
Give the merchant only the scopes it needs:
permission-requests:managefor consent requests andtokens:createfor delivery requests and tokens. Give the resolverresolutions:create. Save each key when it is shown; the secret is not available again after dismissal. - Register a webhook destination
Add an HTTPS endpoint and subscribe to the permission, token, and resolution events your workflow needs. Copy the signing secret once and store it separately from API keys.
Configuration map
base_url is the AddressMask API origin. The organization and client IDs come from the business workspace. An API key belongs to one client, environment, and scope set; it is not the same value as a client ID.
ADDRESSMASK_BASE_URL=https://addressmask.com
ADDRESSMASK_ORGANIZATION_ID=<organization-uuid>
ADDRESSMASK_MERCHANT_CLIENT_ID=<merchant-client-uuid>
ADDRESSMASK_RESOLVER_CLIENT_ID=<resolver-client-uuid>
# Store credentials in your platform's secret manager.
ADDRESSMASK_PERMISSION_API_KEY=<api-key>
ADDRESSMASK_TOKEN_API_KEY=<api-key>
ADDRESSMASK_RESOLVER_API_KEY=<api-key>
ADDRESSMASK_WEBHOOK_SECRET=<secret>
Client roles and disclosure capabilities depend on this deployment. If an option or endpoint is unavailable, check its served OpenAPI contract and ask your workspace administrator before integrating it.
Know which system creates, stores, and uses each value.
AddressMask separates public references, consumer authorization, merchant orchestration, and resolver-only disclosure. Do not collapse these roles into one unrestricted credential.
- Consumer → merchantAddressMask
Public
AM-…identifier supplied through your user experience. It is not a credential and reveals nothing alone. - Merchant → consumerPermission request
Names the organization, purpose, resolver, requested result, reason, expiry, and consumer-visible scope.
- Consumer → merchantPolicy ID
Appears only after approval. It authorizes later issuance within its exact scope until expiry or revocation.
- Merchant orchestrationDelivery request
Binds a unique shipment reference to one mask and one active shipping policy. The raw reference is not returned later.
- Merchant → resolverAccess token
Secret, short-lived, resolver-bound, field-scoped, and exactly one successful use for shipping.
- Resolver onlyResolution result
The authorized result is returned to the authenticated resolver. The token is consumed atomically on success.
- Integration callbackWebhook event
Signed, privacy-safe metadata for workflow state changes. It never contains the resolved address or bearer token.
Implement the sequence as a resumable state machine.
Do not perform all calls in one fragile synchronous chain. Save every returned ID, stop while consumer approval is pending, and resume from the last durable state after a webhook, poll, or retry.
1. Collect the mask and request permission
Obtain the customer's AM-… identifier in your user experience, validate its format, then send this request from the merchant backend. The reason is visible to the consumer; use a recognizable order or case reference without adding unnecessary personal data.
POST /api/v1/permission-requests
Authorization: Bearer amk_live_<merchant-key>
Content-Type: application/json
Idempotency-Key: permission-order-10482
{
"organization_id": "11111111-1111-4111-8111-111111111111",
"requesting_client_id": "22222222-2222-4222-8222-222222222222",
"mask": "AM-23456789ABCDEFGH",
"resolver_client_id": "33333333-3333-4333-8333-333333333333",
"purpose": "SHIPPING",
"audience": {
"type": "resolver",
"id": "33333333-3333-4333-8333-333333333333"
},
"requested_fields": ["full_delivery_address"],
"request_reason": "Deliver order 10482 to the customer",
"requested_expires_at": "<RFC3339 timestamp 5 minutes to 90 days from now>",
"max_resolution_uses": 1
}HTTP/1.1 201 Created
X-Request-Id: req_<request-id>
{
"data": {
"permission_request_id": "44444444-4444-4444-8444-444444444444",
"status": "PENDING",
"policy_id": null,
"policy_version": null
},
"request_id": "req_<request-id>"
}2. Pause until the consumer decides
A 201 PENDING response is not permission. Subscribe to permission.granted and permission.denied, or poll the detail endpoint at a bounded interval. Continue only when status is APPROVED and authorization contains a policy ID.
GET /api/v1/permission-requests/44444444-4444-4444-8444-444444444444?organization_id=11111111-1111-4111-8111-111111111111
Authorization: Bearer amk_live_<permission-key>
Accept: application/jsonHTTP/1.1 200 OK
X-Request-Id: req_<request-id>
{
"data": {
"permission_request": {
"id": "44444444-4444-4444-8444-444444444444",
"status": "APPROVED",
"authorization": {
"policy_id": "77777777-7777-4777-8777-777777777777",
"policy_version": 1,
"expires_at": "<policy expiry returned by AddressMask>",
"max_token_ttl_seconds": 86400,
"max_resolution_uses": 1,
"revocation_effect": "REVOKES_ACTIVE_TOKENS_AND_PENDING_DELIVERIES"
}
},
"capability_enabled": true
},
"request_id": "req_<request-id>"
}3. Create one delivery request for the shipping job
Use your stable order or shipment identifier as shipment_ref. AddressMask stores a protected lookup, not the raw reference. A different Idempotency-Key with the same shipment reference does not create a second shipping job.
POST /api/v1/delivery-requests
Authorization: Bearer amk_live_<merchant-key>
Content-Type: application/json
Idempotency-Key: idem_order_10482
{
"mask": "AM-23456789ABCDEFGH",
"policy_id": "77777777-7777-4777-8777-777777777777",
"shipment_ref": "ORDER-10482"
}{
"data": {
"delivery_request_id": "88888888-8888-4888-8888-888888888888",
"status": "PENDING"
},
"request_id": "req_<request-id>"
}4. Issue the short-lived resolver token
The token-creation call uses the exact policy, delivery request, purpose, resolver audience, and field approved in the preceding steps. The returned amt_live_… value is secret and is shown only in this response.
POST /api/v1/masks/AM-23456789ABCDEFGH/tokens
Authorization: Bearer amk_live_<merchant-key>
Content-Type: application/json
Idempotency-Key: idem_token_10482
{
"policy_id": "77777777-7777-4777-8777-777777777777",
"purpose": "SHIPPING",
"audience": {
"type": "resolver",
"id": "33333333-3333-4333-8333-333333333333"
},
"delivery_request_id": "88888888-8888-4888-8888-888888888888",
"requested_fields": ["full_delivery_address"],
"expires_in_seconds": 7200
}HTTP/1.1 201 Created
X-Request-Id: req_<request-id>
{
"data": {
"token_id": "55555555-5555-4555-8555-555555555555",
"token": "amt_live_<one-time-secret>",
"status": "ACTIVE",
"purpose": "SHIPPING",
"requested_fields": ["full_delivery_address"],
"expires_at": "<token expiry returned by AddressMask>"
},
"request_id": "req_<request-id>"
}5. Deliver the token to the authorized resolver
Transfer the token through a protected server-to-server channel, not through the customer's browser. The resolver authenticates with its own resolutions:create key and presents the same shipment reference. The merchant key cannot perform this operation.
POST /api/v1/resolutions
Authorization: Bearer amk_live_<resolver-key>
Content-Type: application/json
Idempotency-Key: idem_resolve_10482
{
"token": "amt_live_<one-time-secret>",
"shipment_ref": "ORDER-10482",
"requested_fields": ["full_delivery_address"]
}HTTP/1.1 200 OK
X-Request-Id: req_<request-id>
{
"data": {
"decision": "ALLOW",
"resolution_id": "66666666-6666-4666-8666-666666666666",
"result": {
"address": {
"recipient_name": "Example Customer",
"line1": "100 Example Street",
"line2": null,
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country_code": "US"
}
},
"consumed": true
},
"request_id": "req_<request-id>"
}6. Finalize from the API response and webhooks
Treat decision: ALLOW plus the returned result as the disclosure outcome. Store only the business metadata you need. Use signed webhook events to update asynchronous workflow state, and expect duplicate deliveries. A second use of a consumed shipping token returns generic 404 TOKEN_UNAVAILABLE.
Generate a different Idempotency-Key for each distinct mutation. When retrying the same mutation after a timeout, reuse its original key and identical body. Replace angle-bracket placeholders before sending an example. Never place API keys or amt_tokens in URLs, browser storage, analytics, tickets, or logs.
Minimum state to persist in your workflow
permission_request_idCorrelates consumer approval or denial.policy_idAvailable after approval; required for delivery and token creation.shipment_refYour stable business reference; reuse it through resolution.delivery_request_idRequired to issue the shipping token.token_id + expires_atOperational metadata only; avoid retaining the token secret.resolution_idCorrelates the final decision, audit record, and webhook.Idempotency-Key per mutationRequired to recover safely from an unknown response.request_idSafe diagnostic correlation value for support.Endpoints are generated from the same contract as validation.
Every mutation requires Idempotency-Key. API keys are sent only as Bearer credentials. Consumer mutations use the secure session cookie plus same-origin enforcement.
Credential and responsibility matrix
permission-requests:manageMerchant client onlytokens:createMerchant client onlyresolutions:createSeparate resolver clientwebhooks:manageNever needed by runtime workersdeliveries:updateOnly when the capability is enabledJoin https://addressmask.com with the documented path exactly once. Do not duplicate /api/v1.
Send Authorization: Bearer amk_live_…. Do not send the client ID as the bearer credential.
Send Content-Type: application/json and one stable Idempotency-Key per logical mutation.
Record the body request_id or response X-Request-Id. They identify the same request.
address updates
GET/api/v1/address-updatesList pending address update receiptsPOST/api/v1/address-updates/{id}/acknowledgementsAcknowledge an address update onceorganizations
GET/api/v1/organizations/{id}/widgetsList registered checkout widgetsPOST/api/v1/organizations/{id}/widgetsRegister merchant origins and callback URLsGET/api/v1/organizationsList organizations, API clients, and key metadataPOST/api/v1/organizationsCreate a merchant organizationPOST/api/v1/organizations/{id}/clientsCreate an environment-bound API clientGET/api/v1/organizations/{id}/clientsList API clients for an organizationPOST/api/v1/organizations/{id}/clients/{client_id}Update non-secret API-client metadataPOST/api/v1/organizations/{id}/clients/{client_id}/suspendSuspend an API clientPOST/api/v1/organizations/{id}/clients/{client_id}/reactivateReactivate an API clientPOST/api/v1/organizations/{id}/clients/{client_id}/revokeRevoke an API clientGET/api/v1/organizations/{id}/invitationsList protected organization invitation metadataPOST/api/v1/organizations/{id}/invitationsInvite a member to an organizationPOST/api/v1/organizations/{id}/invitations/{invitation_id}/revokeRevoke a pending organization invitationGET/api/v1/organizations/{id}/membersList organization membership metadataPOST/api/v1/organizations/{id}/members/{membership_id}/roleChange a non-owner member rolePOST/api/v1/organizations/{id}/members/{membership_id}/removeRemove a non-owner organization memberPOST/api/v1/organizations/{id}/ownership-transferAtomically transfer organization ownershipPOST/api/v1/organizations/{id}/suspendSuspend an organizationPOST/api/v1/organizations/{id}/reactivateReactivate an organizationPOST/api/v1/organizations/{id}/closeClose an organizationGET/api/v1/organizations/{id}/service-area-rule-setsList service-area rule-set metadataPOST/api/v1/organizations/{id}/service-area-rule-setsCreate an immutable service-area rule-set versionPOST/api/v1/organizations/{id}/service-area-rule-sets/{rule_set_id}/activateActivate one service-area rule-set versionPOST/api/v1/organizations/{id}/keysCreate a scoped API keyPOST/api/v1/organizations/{id}/keys/{key_id}/rotateRotate an API key with a bounded overlapPOST/api/v1/organizations/{id}/keys/{key_id}/revokeRevoke an API keyGET/api/v1/organizations/{id}/usageGet privacy-safe organization usage totalsGET/api/v1/organizations/{id}/authorization-ledgerList redacted authorization operationscheckout sessions
POST/api/v1/checkout-sessionsStart a shipping checkout authorizationGET/api/v1/checkout-sessions/{session_id}Read checkout consent detailsPOST/api/v1/checkout-sessions/{session_id}/decisionApprove or cancel a checkoutPOST/api/v1/checkout-sessions/exchangeExchange a one-use checkout code using PKCEaddresses
POST/api/v1/addressesCreate an encrypted address vault versionDELETE/api/v1/addressesDelete the current protected addressPOST/api/v1/addresses/{id}/verifyStart or refresh address verificationGET/api/v1/addresses/{id}/correctionRetrieve the user's entered address for correctionGET/api/v1/addresses/{id}/confirmationReview a provider-normalized address candidatePOST/api/v1/addresses/{id}/confirmConfirm the exact reviewed address candidatemasks
POST/api/v1/masksCreate an AddressMask for a verified vaultGET/api/v1/masksList visible AddressMasksGET/api/v1/masks/{mask}Get non-sensitive AddressMask metadataPOST/api/v1/masks/{mask}/revokeRevoke an AddressMask and its active credentialsPOST/api/v1/masks/{mask}/tokensIssue a purpose-bound access tokendashboard
GET/api/v1/dashboardGet the consumer protection snapshotvault
POST/api/v1/vault/revealReveal the consumer's protected addresspermissions
GET/api/v1/permissionsList the consumer's disclosure permissionsPOST/api/v1/permissions/{policy_id}/revokeRevoke a disclosure policypermission requests
GET/api/v1/permission-requestsList merchant permission-request metadataPOST/api/v1/permission-requestsRequest exact consumer permissionGET/api/v1/permission-requests/{permission_request_id}Inspect a merchant permission requestPOST/api/v1/permission-requests/{permission_request_id}/revokeRevoke a permission request and descendantsconsumer
GET/api/v1/consumer/permission-requestsList permission requests for the consumerGET/api/v1/consumer/permission-requests/{permission_request_id}Inspect a consumer permission requestPOST/api/v1/consumer/permission-requests/{permission_request_id}/approveApprove an exact permission requestPOST/api/v1/consumer/permission-requests/{permission_request_id}/denyDeny a permission requestdelivery requests
POST/api/v1/delivery-requestsCreate a shipment-bound delivery requesttokens
POST/api/v1/tokens/{token_id}/revokeRevoke an access token by its non-secret IDresolutions
POST/api/v1/resolutionsResolve an authorized access tokenorganization invitations
POST/api/v1/organization-invitations/acceptAccept an email-bound organization invitationwebhooks
GET/api/v1/webhooksList webhook subscriptionsPOST/api/v1/webhooksCreate a signed webhook subscriptionPOST/api/v1/webhooks/{webhook_id}/deactivateDeactivate a webhook subscriptionPOST/api/v1/webhooks/{webhook_id}/rotate-secretRotate a webhook signing secretGET/api/v1/webhooks/{webhook_id}/deliveriesList webhook delivery attemptsPOST/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/replayReplay a dead-lettered webhook deliverynotifications
GET/api/v1/notificationsList durable consumer notificationsGET/api/v1/notifications/preferencesGet routine product-email preferencesPOST/api/v1/notifications/preferencesUpdate routine product-email preferencesPOST/api/v1/notifications/{notification_id}/readMark a consumer notification as readPOST/api/v1/notifications/readMark all consumer notifications as readaudit events
GET/api/v1/audit-eventsList visible redacted audit eventsauth
GET/api/v1/auth/sessionsList active authenticated sessionsDELETE/api/v1/auth/sessions/{session_id}Revoke another authenticated sessionPOST/api/v1/auth/account-recovery/startStart account deletion recoveryPOST/api/v1/auth/account-recovery/consumeConfirm account deletion recoveryaccount
POST/api/v1/account/deletionSchedule authenticated account deletionGET/api/v1/account/exportsList encrypted account export jobsPOST/api/v1/account/exportsCreate a one-use encrypted account archivePOST/api/v1/account/exports/{export_id}/downloadConsume a one-use encrypted account archiveopenapi
GET/api/v1/openapiGet the OpenAPI 3.1 contractRead the code, then act on the cause.
Errors include a stable code and a request_id that matches the X-Request-Id response header. Share the ID with support, never the API key or access token.
400 INVALID_REQUESTCheck JSON, required fields, allowed values, and the Idempotency-Key header.401 UNAUTHENTICATEDSend a valid bearer API key from your server.403 FORBIDDENCheck the client role, key scope, and organization access.403 POLICY_DENIEDConfirm approval, purpose, resolver audience, field, and shipment binding. Do not retry unchanged.403 CONSENT_REQUIREDThe consumer has not granted an active consent for the exact policy version. Return the workflow to permission status; do not create another token blindly.403 VERIFICATION_REQUIREDThe protected address is not eligible for disclosure in this deployment. Ask the consumer to complete the required address verification; retries alone will not change the result.403 STEP_UP_REQUIREDConfirm recent authentication in the business workspace before changing credentials.404 TOKEN_UNAVAILABLEThe token cannot be used. Its precise state is intentionally hidden; request a new approved token if needed.409 IDEMPOTENCY_CONFLICTUse the original body for a retry, or a new key for a genuinely new operation.429 RATE_LIMITEDWait for the Retry-After interval before retrying.503 CAPABILITY_UNAVAILABLEThe endpoint or feature is disabled here. Check this deployment's OpenAPI document.HTTP/1.1 409 Conflict
X-Request-Id: req_<request-id>
{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "The idempotency key was used with different parameters."
},
"request_id": "req_<request-id>"
}For a network failure, repeat the same request body with the same Idempotency-Key. Do not generate a new key just because the first response was lost. A consumed token does not become reusable with a new key. Automatically retry only timeouts, selected 5xx responses, and 429 after Retry-After; surface authentication, policy, consent, and validation errors for corrective action.
Verify the raw request before trusting the event.
Deliveries are at-least-once. The Unix timestamp is the t value inside the addressmask-signature header; it is not sent in a second timestamp header. Reject a delivery more than 300 seconds from your clock, then deduplicate the stable event ID before applying any business effect.
Create the subscription once
You can configure the destination in the business workspace or with a webhooks:manage key. The endpoint must be public HTTPS. The signing secret is returned only when created or rotated; copy it directly into your secret store.
POST /api/v1/webhooks
Authorization: Bearer amk_live_<webhook-management-key>
Content-Type: application/json
Idempotency-Key: idem_webhook_setup_01
{
"organization_id": "11111111-1111-4111-8111-111111111111",
"endpoint": "https://integration.example.com/addressmask/events",
"events": [
"permission.granted",
"permission.denied",
"token.created",
"resolution.allowed",
"resolution.denied"
]
}Portable verification algorithm
- Read and preserve the exact raw UTF-8 request body.
- Parse
tandv1from the signature header and reject an old or malformed timestamp. - Compute HMAC-SHA256 using the webhook secret over
t + "." + rawBody. - Compare the supplied and calculated digests in constant time.
- Confirm the event header equals the body
id, then persist that ID as a unique deduplication key. - Commit the business effect and deduplication record together, then return any 2xx status.
- addressmask-signature
t=<unix-seconds>,v1=<hex-digest>using HMAC-SHA256 over<unix-seconds>.<raw-request-body>.- addressmask-event-id
- Must equal the envelope
id. Persist this value as the business-event deduplication key across retries and replay. - addressmask-delivery-id
- Delivery correlation only. A signed replay can have a new delivery ID while retaining the same event ID.
AddressMask emits UTF-8 compact JSON with object keys sorted lexicographically at every depth; array order is preserved. Verify the exact raw UTF-8 body you received—never parse and reserialize it before computing the digest. Return a 2xx response only after the event ID and its business effect are durably committed together.
application/json{
"id": "evt_01J6N7Q6Q0M9T6A4K2Y8V3C5P1",
"type": "permission.granted",
"occurred_at": "2026-08-31T12:00:00.000Z",
"data": {
"permission_request_id": "prq_01J6N7NZX7M8H4P2Q9R5C3T1V6",
"purpose": "SHIPPING",
"status": "APPROVED"
}
}raw bytes · constant timeimport { createHmac, timingSafeEqual } from "node:crypto";
const rawBody = await request.text(); // capture before JSON parsing
const signature = request.headers.get("addressmask-signature") ?? "";
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature);
if (!match) return new Response("Invalid signature", { status: 400 });
const timestamp = Number(match[1]);
const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
if (!Number.isSafeInteger(timestamp) || age > 300) {
return new Response("Expired signature", { status: 400 });
}
const expected = createHmac("sha256", process.env.ADDRESSMASK_WEBHOOK_SECRET!)
.update(String(timestamp) + "." + rawBody, "utf8")
.digest();
const supplied = Buffer.from(match[2], "hex");
if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(rawBody);
const eventId = request.headers.get("addressmask-event-id");
if (eventId !== event.id) return new Response("Event mismatch", { status: 400 });
await applyEventOnce(event.id, event); // persist the dedupe key with the effect
return new Response(null, { status: 204 });Keep the browser outside the disclosure boundary.
A frontend may collect the public mask and show workflow status. API keys, webhook secrets, and amt_… tokens belong only in protected backend or integration-runtime execution.
Never embed an amk_… key in the current widget, a public page, client-side script, downloadable application, or customer-visible callback.
Merchant clients issue tokens. Resolver clients resolve them. Do not give either client every scope.
Identical retries replay the stored response. Reusing a key with different parameters is rejected.
Treat deliveries as at-least-once, deduplicate event IDs, and rotate secrets through the business console.
Deliver each token only to its named resolver over an authenticated channel. Do not persist the secret after handoff unless your recovery design requires encrypted, tightly time-bounded storage.
Before moving an integration to production
- Use production clients and
amk_live_…keys. - Confirm every key has only its required job scope.
- Keep merchant and resolver credentials in separate stores.
- Exercise approval, denial, revocation, and expiry paths.
- Prove timeout retries reuse the original idempotency key.
- Verify webhook signatures using raw bytes and deduplicate IDs.
- Redact authorization headers, tokens, addresses, and secrets from logs.
- Alert on repeated 401, 403, 429, 5xx, and webhook dead letters.
- Rotate API keys and webhook secrets without an outage.
- Validate the complete flow using the served OpenAPI contract.
