Conservez les adresses. Utilisez le nécessaire.

Comment commencer

Souscrivez au plan DEV, connectez-vous au portail avec Microsoft et associez l’achat. Demandez la préparation. Vérifiez organisation, contrat, Vault, applications, droits et conservation avant approbation et activation, puis testez avec des données fictives. L’achat ne crée pas automatiquement d’environnement ni de droits. Convenez séparément des conditions de production.

Avant la connexion

Convenez avec OneNym du contrat, de l’organisation, du tenant Vault, des IDs des applications marchand et transporteur, de la finalité, des champs et de la conservation. Obtenez l’origine HTTPS de l’API, API application ID et directory tenant ID. Le site et le portail d’achat ne sont pas l’API. Configuration et approbation restent nécessaires après l’achat.

Utilisez les jetons Bearer applicatifs Microsoft Entra : Managed Identity sur Azure ou clé privée de certificat pour obtenir le jeton. Il ne s’agit pas de mTLS. Le Vault actuel fait confiance à un seul annuaire Entra ; une autre organisation n’est pas admise automatiquement. Gardez les identifiants côté serveur.

ONENYM_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>

Exécuter l’exemple local

Demandez à OneNym le paquet contenant les sources du SDK et l’exemple. Extrayez-le dans un nouveau dossier. Installez .NET 10 SDK et PowerShell 7 avec accès à NuGet. Les commandes vérifient 18 opérations fictives sans compte Azure. L’authentification, SQLite et les clés locales servent uniquement à la démonstration. Utilisez les sources incluses ; aucune distribution NuGet publique n’est présumée.

dotnet --version
pwsh --version
pwsh -NoProfile -File ./samples/OneNym.Vault.Pilot/run-local.ps1

RESULT passed=True; steps=18; elapsedMs=…; cleanup=True
PASS isolated customer quickstart

De la commande à la livraison

1. 01 / REGISTER

   Enregistrez une adresse via l’API authentifiée. Vault la chiffre et renvoie un identifiant imprévisible. Évitez aussi les copies dans les serveurs et journaux applicatifs.

2. 02 / REFERENCE

   Conservez la commande et l’identifiant proxy dans votre base. Cet identifiant n’est ni l’adresse ni un droit d’accès. L’intégration ne supprime pas les copies existantes : prévoyez migration et suppression.

3. 03 / AUTHORIZE

   Associez commande, identifiant, application destinataire, champs et expiration. Émettez un jeton à usage limité. Le jeton seul ne donne pas accès.

4. 04 / RETRIEVE

   Authentifiez l’application puis vérifiez organisation, commande, finalité, champs, expiration, usages et contrat. Les champs autorisés sont renvoyés en clair : leur stockage côté destinataire doit aussi être contrôlé.

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 fields

Ces échantillons expliquent la conception. Les noms et valeurs des champs sont donnés à titre indicatif et ne constituent pas une référence API exécutable.

L’adresse entière est déchiffrée en mémoire, puis seuls les champs autorisés sont renvoyés. Ce n’est pas un chiffrement par champ. Gérez le texte reçu ainsi que les journaux et stockages précédant l’enregistrement.

Opérations API et SDK

Chaque opération nécessite un Bearer applicatif et des autorisations. L’utilisation du jeton nécessite aussi X-OneNym-Retrieval-Token. Utilisez JSON UTF-8 et la finalité shipping. GET, révocation et DELETE n’ont pas de corps. Le fragment suppose merchant et carrier authentifiés, persistedKey enregistrée avant l’opération et orderReference sans données personnelles. Le paquet contient l’application exécutable.

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);

Champs, expiration et utilisations

Les sept champs figurent ci-dessous. countryCode contient deux majuscules ; le JSON est limité à 16 384 octets. La conservation maximale initiale est de 30 jours, selon la configuration. Un jeton expire au plus tard avec l’adresse et la commande et dans les 15 minutes suivant son émission. maxUses vaut 1 à 5 dans l’API, un dans le SDK standard. L’expiration utilise les secondes UTC et exclut l’instant limite. L’existence et la validité postale ne sont pas vérifiées.

recipientName   1–200
postalCode      1–32
countryCode     [A-Z]{2}
addressLine1    1–300
addressLine2    null / 0–300
locality        1–100
region          null / 0–100

Corrections, commandes et révocation

Enregistrez une nouvelle adresse au lieu de modifier l’existante. Consultez le lien, transmettez sa Version comme expectedVersion, modifiez la commande puis émettez un jeton pour sa nouvelle version. Les jetons des anciennes versions sont bloqués. Émettre un autre jeton à version identique ne révoque pas les précédents. Vérifiez les autres commandes et la conservation avant suppression. Le texte déjà transmis ne peut être rappelé.

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.

Erreurs et résultats inconnus

Le SDK ne réessaie jamais automatiquement. Un délai dépassé, une annulation ou un 503 peut survenir après écriture ou consommation du jeton. Vérifiez le résultat avant de répéter une opération.

400 / 413 / 415

Vérifiez données, propriétés JSON répétées ou inconnues, types et dates. 400 : entrée invalide ; 413 : corps trop volumineux ; 415 : format non pris en charge. Ne modifiez pas silencieusement les valeurs avant renvoi.

401 / 403 / 404

Vérifiez identité, audience, droits applicatifs, champs, finalité et contrat. Un 404 peut masquer une ressource tierce, révoquée ou supprimée ; il ne prouve ni présence ni absence.

409

Vérifiez expiration, utilisations, version et conflit de clé d’idempotence. Consultez le lien pour résoudre les modifications concurrentes. Ne remplacez pas automatiquement les clés ou jetons.

429 / Retry-After

Une limite configurée est atteinte. Respectez Retry-After, bornez la concurrence et vérifiez si l’opération peut être répétée. Aucun délai ni débit n’est garanti.

SDK / 503

SDK 408/timeout_outcome_unknown, 0/transport_unavailable, 502/invalid_response, annulation et API 503 peuvent laisser un résultat inconnu. Récupérez l’enregistrement uniquement avec la même clé sauvegardée, le corps et l’expiration d’origine. Le reçu dure au plus 24 heures ou jusqu’à la fin de conservation. Consultez le binding de commande. Le jeton brut ne peut être relu ; vérifiez le traitement de livraison avant réémission ou révocation.

Indiquez statut HTTP, heure et trace ID si disponible. N’envoyez jamais adresses, Bearer, clés privées ou jetons de livraison au support.

Périmètre implémenté et vérifié

Enregistrement, lecture limitée aux champs, commandes versionnées, jetons, nombre d’utilisations, révocation, suppression et expiration sont implémentés. SDK, SQL isolé et Azure réel avec MI, Key Vault, Azure SQL et historique vérifient fonctionnement, refus, concurrence et reprise. Achat et consentement réels d’une autre organisation et notifications Microsoft réelles de suspension/reprise restent à valider. Ces tests ne constituent pas un SLA ni une garantie de capacité universelle.

FAQ

Conceptions techniques associées