ADDRESS VAULT / GETTING STARTED
OneNym Address Vault is an API service that encrypts delivery addresses and lets business systems reference them by proxy ID. Only permitted fields are returned to an authorized application.
The purchase portal and cloud API evaluation environment are currently paused. Contact us about onboarding, evaluation or resuming access. The instructions below apply after the environment resumes.
Subscribe to the Marketplace DEV plan, sign in to the OneNym portal with Microsoft and link the purchase. Request setup. Confirm the organization, contract, Vault, application permissions and retention settings before approval and activation, then test API integration with dummy data. Purchasing does not automatically create an environment or grant data access. Agree production scope and terms during onboarding.
Agree the purchase, organization, Vault tenant, merchant and delivery application IDs, purpose, allowed fields and retention with OneNym. Obtain the API HTTPS origin, API application ID and directory tenant ID. This website and the purchase portal are not the API origin. Setup and approval are required after purchase.
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.
OneNymONENYM_API_URL=<API HTTPS origin>
ONENYM_API_APPLICATION_ID=<API application ID>
directory tenant ID / merchant client ID / carrier client ID
Authorization: Bearer <application-access-token>Obtain the SDK source and sample package from OneNym and extract it into a fresh folder. Install .NET 10 SDK and PowerShell 7, with access to NuGet dependencies. The commands below verify 18 dummy-data operations without an Azure account. Local authentication, SQLite and keys are for the demo, not a way to bypass service authentication or contracts. Reference the included SDK source; a public NuGet release is not assumed.
dotnet --version
pwsh --version
pwsh -NoProfile -File ./samples/OneNym.Vault.Pilot/run-local.ps1RESULT passed=True; steps=18; elapsedMs=…; cleanup=True PASS isolated customer quickstart
Register an address through the authenticated Vault API. It stores encrypted data and returns an unpredictable proxy ID. Design the input and integration path so addresses are not also retained in application logs or servers.
Keep the order reference and proxy ID in your business database. A proxy ID is neither the address nor permission to retrieve it. Integrating the API does not remove existing copies; migration and deletion are separate steps.
Bind the order and proxy ID to a recipient application, fields and expiry. Issue a retrieval token with a usage limit for that order. Possession of the token alone does not authorize access.
Authenticate the delivery application and check tenant, order, purpose, fields, expiry, usage and contract eligibility. Permitted fields are returned as plaintext, so recipients must also control storage and logging.
POST /v1/addresses
→ proxyId: nym_…
PUT /v1/shipping-orders
proxyId + orderReference + recipientClientId + fields + expiresAt
→ orderId + version
POST /v1/shipping-orders/{orderId}/grants
orderVersion + expiresAt + maxUses
→ token: nrt_…
POST /v1/retrieval-grants/redeem
Authorization: Bearer <application-access-token>
X-OneNym-Retrieval-Token: <retrieval-token>
orderId + orderReference + purpose + fields
→ permitted fieldsThese samples explain the design. Field names and values are illustrative, not an executable API reference.
The implementation decrypts the entire address record in memory and projects only permitted fields into the response. It is not field-level encryption. Recipients must manage returned plaintext; customers must also manage logs and storage along the registration path.
Every operation requires an application Bearer token and the appropriate permissions. Redemption also requires X-OneNym-Retrieval-Token. Use UTF-8 JSON and purpose shipping. Send no body for GET, revocation or DELETE. The code below assumes authenticated merchant and carrier clients, a persistedKey saved before registration, and an orderReference without personal data. It is an SDK fragment; use the integration package for a runnable application.
| Operation | Method and path | Success |
|---|---|---|
| Register address | POST /v1/addressesRegisterAsync(…) | 201 |
| Retrieve allowed fields | POST /v1/addresses/{proxyId}/retrieveReadAsync(…) | 200 |
| Find order ID and version | GET /v1/shipping-orders/by-reference/{orderReference}FindOrderAsync(…) | 200 |
| Inspect current order binding | GET /v1/shipping-orders/by-reference/{orderReference}/bindingInspectOrderAsync(…) | 200 |
| Create or change order binding | PUT /v1/shipping-ordersBindAsync(…) | 200 |
| Issue delivery token | POST /v1/shipping-orders/{orderId}/grantsIssueAsync(…) | 201 |
| Redeem delivery token | POST /v1/retrieval-grants/redeemRedeemAsync(…) | 200 |
| Revoke one token | POST /v1/retrieval-grants/{grantId}/revokeRevokeGrantAsync(…) | 204 |
| Revoke address | POST /v1/addresses/{proxyId}/revokeRevokeAsync(…) | 204 |
| Delete address | DELETE /v1/addresses/{proxyId}DeleteAsync(…) | 204 |
using OneNym.Vault.Client;
var fields = new[] { "recipientName", "postalCode", "addressLine1" };
var registration = await merchant.RegisterAsync(new CreateAddress {
Address = new AddressData {
RecipientName = "Demo Recipient", PostalCode = "000-0000",
CountryCode = "JP", AddressLine1 = "Dummy address",
Locality = "Demo city"
},
RetainUntil = DateTimeOffset.UtcNow.AddDays(1)
}, persistedKey);
var order = await merchant.BindAsync(new BindOrder(
orderReference, registration.ProxyId, carrierClientId, fields,
DateTimeOffset.UtcNow.AddHours(1)));
var grant = await merchant.IssueAsync(
order.OrderId, order.Version, DateTimeOffset.UtcNow.AddMinutes(5));
var address = await carrier.RedeemAsync(
order.OrderId, orderReference, grant.Token, fields);The seven address fields are listed below. countryCode is two uppercase letters; JSON bodies are limited to 16,384 bytes. The initial retention limit is 30 days and follows deployment settings. Delivery tokens must expire within the address and order expiry and within 15 minutes of issuance. API maxUses is 1–5; the standard SDK uses one. Expiry uses UTC seconds and is exclusive: access is denied at the expiry instant. Address existence and deliverability are not validated.
recipientName 1–200
postalCode 1–32
countryCode [A-Z]{2}
addressLine1 1–300
addressLine2 null / 0–300
locality 1–100
region null / 0–100Register 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.
var current = await merchant.InspectOrderAsync(orderReference);
var changed = await merchant.BindAsync(new BindOrder(
orderReference, newRegistration.ProxyId, carrierClientId, fields,
newOrderExpiry, ExpectedVersion: current.Version));
var newGrant = await merchant.IssueAsync(
changed.OrderId, changed.Version, newGrantExpiry);
// BindOrder = complete desired binding, not a partial patch.
// Keep unknown prior outcomes for reconciliation; never blindly retry.The SDK never retries automatically. A timeout, cancellation or 503 may occur after storage or token consumption. Do not assume that a failed response means no operation occurred; reconcile each operation's outcome.
Provide HTTP status, time and a trace ID if available. Never send address contents, Bearer tokens, certificate private keys or delivery tokens to support.
Registration, scoped retrieval, versioned order changes, delivery-token issuance, usage limits, revocation, deletion and expiry cleanup are implemented. SDK and isolated SQL tests and real Azure MI, Key Vault, Azure SQL and history storage verify normal operation, denied access, concurrency and fault recovery. Actual purchase and consent by a different organization and real Microsoft suspend/reinstate notifications remain acceptance checks. These results do not establish a production SLA or capacity for every configuration.
Encryption is one layer. Separate the address database from Azure Key Vault key-use permissions and check retrieval conditions at the API. Encryption alone cannot prevent misuse of a compromised authorized application or exposure of addresses after retrieval.
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.
Revocation blocks future retrieval. Address deletion clears ciphertext and the wrapped data key from the active record. It does not instantly erase recipient copies or retained backups. A suspended contract blocks normal retrieval while owner cleanup remains possible. Agree backup retention and reapplication of deletions during recovery at onboarding.
The current DEV product is a delivery-address API on Azure. Email sending, identity images, OCR and AWS KMS integration are not included. General architecture examples and other-cloud designs are separate from the functions available with this product. Confirm storage location, operating responsibilities and additional integrations during onboarding.