Libre-service pour agents d'IA

En quoi consiste le libre-service pour agents

Un agent d'IA peut demander l'accès à un compte Inférence Nordique, obtenir l'approbation du titulaire du compte, puis gérer lui-même les clés d'inférence de ce compte. Lorsque l'exploitant a activé les paiements des agents, l'agent peut aussi lancer l'ajout d'une carte ou un achat de crédits que le titulaire termine sur Stripe. L'agent ne détient jamais le mot de passe du titulaire, une session de navigateur ni les données d'une carte. Le titulaire garde le contrôle : rien n'est accordé tant que la personne à qui appartient l'adresse courriel n'a pas approuvé la demande, et rien n'est facturé à moins que le titulaire ne paie sur Stripe.

L'API des agents se trouve sous https://northerninference.ca/api/agent/v1/. Elle utilise deux justificatifs distincts, et aucun ne remplace l'autre :

La description lisible par machine de chaque point de terminaison de cette page est agent-openapi.yaml (OpenAPI 3.1). Un résumé destiné aux agents se trouve dans llms.txt.

Les étapes

1. Générez un vérificateur PKCE aléatoire et son défi S256.
2. Envoyez POST /api/agent/v1/enrollments avec l'adresse courriel du titulaire, une étiquette pour votre agent, les portées souhaitées et le défi.
3. Le titulaire reçoit un courriel, ouvre la page d'approbation et approuve. Un nouveau titulaire commence par choisir un mot de passe et accepter les documents juridiques.
4. Interrogez GET /api/agent/v1/enrollments/{id} jusqu'à ce que le statut soit approved.
5. Envoyez POST /api/agent/v1/enrollments/{id}/claim avec le vérificateur. La réponse contient le justificatif ni_mgmt_, affiché une seule fois.
6. Créez une clé d'inférence avec POST /api/agent/v1/keys. Le secret ni_live_ est affiché une seule fois.
7. Alimentez le compte : lancez un achat de crédits avec POST /api/agent/v1/billing/topups. Inférence Nordique envoie le lien Stripe au titulaire par courriel, et celui-ci paie sur Stripe.
8. Interrogez l'achat jusqu'à ce qu'il soit payé, puis appelez les modèles avec la clé ni_live_.

1. Générer un vérificateur et un défi

Le vérificateur est une chaîne aléatoire de 43 à 128 caractères parmi A-Z a-z 0-9 - . _ ~. Gardez-le secret : c'est lui qui prouve que la réclamation provient de l'agent qui a fait la demande. Le défi est le SHA-256 du vérificateur, encodé en base64url sans remplissage, toujours de 43 caractères.

CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
echo "$CODE_CHALLENGE"

La même chose en Python :

import base64, hashlib, secrets

code_verifier = secrets.token_urlsafe(64)  # 86 characters
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode("ascii")).digest()
).rstrip(b"=").decode("ascii")

2. Demander l'accès

Envoyez un en-tête Idempotency-Key de 8 à 200 caractères ASCII imprimables. Répéter la même demande avec la même clé renvoie la même inscription et n'envoie pas de second courriel. La même clé avec une demande différente est refusée avec 409 idempotency_key_reused.

curl -sS https://northerninference.ca/api/agent/v1/enrollments \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "owner@example.org",
    "agent_label": "Release notes agent",
    "scopes": ["account:read", "keys:read", "keys:write"],
    "code_challenge": "'"$CODE_CHALLENGE"'",
    "code_challenge_method": "S256",
    "account_name": "Example Org"
  }'

agent_label compte de 1 à 80 caractères et est montré au titulaire. account_name est facultatif et sert seulement à nommer un nouveau compte. La réponse est 202 Accepted et a la même forme, que l'adresse ait déjà un compte ou non :

{
  "enrollment_id": "0b5c1d2e-7a54-4f55-9d3e-2c7f1d6a8e10",
  "status": "pending",
  "expires_at": "2026-10-13T15:04:05+00:00",
  "agent_label": "Release notes agent",
  "scopes": ["account:read", "keys:read", "keys:write"],
  "owner_action": "Nothing is granted until the owner of this email address approves the request from the email Northern Inference sends them. Poll status_url, then claim.",
  "status_url": "/api/agent/v1/enrollments/0b5c1d2e-7a54-4f55-9d3e-2c7f1d6a8e10",
  "claim_url": "/api/agent/v1/enrollments/0b5c1d2e-7a54-4f55-9d3e-2c7f1d6a8e10/claim"
}

La demande reste ouverte pendant 24 heures. Une seule demande par adresse courriel peut être en attente à la fois.

3. Le titulaire approuve

Inférence Nordique envoie au titulaire un lien à usage unique vers /agent-approve.html. La page présente l'étiquette de l'agent et ce que permet chaque portée. Rien ne se produit au chargement de la page : le titulaire doit cliquer. Un nouveau titulaire choisit un mot de passe et accepte les versions en vigueur des Conditions d'utilisation, de la Politique de confidentialité et de la Politique d'utilisation acceptable. Un titulaire existant ouvre d'abord une session et passe la vérification à deux facteurs si elle est configurée. Le titulaire peut aussi refuser. L'agent ne peut pas approuver sa propre demande.

4. Interroger le statut

curl -sS https://northerninference.ca/api/agent/v1/enrollments/$ENROLLMENT_ID

La réponse contient les mêmes champs qu'à l'étape 2. status vaut pending, approved, declined, expired ou claimed. Interrogez au plus toutes les quelques secondes : le point de terminaison de statut accepte 240 appels par heure par adresse IP. Arrêtez-vous à declined ou expired et présentez une nouvelle demande si le titulaire le souhaite toujours.

5. Réclamer le justificatif

curl -sS -X POST https://northerninference.ca/api/agent/v1/enrollments/$ENROLLMENT_ID/claim \
  -H "Content-Type: application/json" \
  -d '{"code_verifier": "'"$CODE_VERIFIER"'"}'

{
  "credential": "ni_mgmt_...",
  "token_type": "Bearer",
  "credential_id": "5f0e3c1a-9b1d-4c0e-8a55-61c7d0f2b3a4",
  "key_prefix": "ni_mgmt_AbCdEfGh",
  "scopes": ["account:read", "keys:read", "keys:write"],
  "expires_at": "2027-01-10T15:09:41+00:00",
  "note": "Shown once. Northern Inference keeps only a hash and cannot show it again."
}

Conservez le justificatif immédiatement. Inférence Nordique n'en garde qu'une empreinte et ne l'affiche qu'une seule fois; une seconde réclamation répond 409 already_claimed sans aucun secret. Un justificatif dure 90 jours. Les portées ne peuvent pas être élargies par la suite : pour en obtenir davantage, présentez une nouvelle demande.

6. Gérer les clés

Envoyez le justificatif sous la forme Authorization: Bearer ni_mgmt_....

export NI_MGMT=ni_mgmt_YOUR_CREDENTIAL

# Read the account (account:read)
curl -sS https://northerninference.ca/api/agent/v1/account \
  -H "Authorization: Bearer $NI_MGMT"

# List keys (keys:read)
curl -sS https://northerninference.ca/api/agent/v1/keys \
  -H "Authorization: Bearer $NI_MGMT"

# Create a key (keys:write). Idempotency-Key is required.
curl -sS https://northerninference.ca/api/agent/v1/keys \
  -H "Authorization: Bearer $NI_MGMT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "release-notes-agent",
    "allowed_privacy_tiers": ["managed_canadian_cloud"],
    "max_rpm": 60,
    "max_budget_cents": 500
  }'

Une première création répond 201 avec les paramètres de la nouvelle clé et, une seule fois, le secret dans key :

{
  "id": "c9d8e7f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "key_prefix": "ni_live_AbCd",
  "name": "release-notes-agent",
  "allowed_privacy_tiers": ["managed_canadian_cloud"],
  "max_rpm": 60,
  "max_budget_cents": 500,
  "...": "other key settings",
  "key": "ni_live_...",
  "secret_already_issued": false
}

Si la réponse est perdue, une nouvelle tentative avec le même Idempotency-Key et le même corps répond 200 avec les paramètres de la clé et "secret_already_issued": true. Elle ne renvoie jamais le secret de nouveau et ne crée jamais de seconde clé. Pour récupérer l'accès, faites pivoter la clé.

# Change settings (keys:write). Only the fields you send change.
curl -sS -X PATCH https://northerninference.ca/api/agent/v1/keys/$KEY_ID \
  -H "Authorization: Bearer $NI_MGMT" \
  -H "Content-Type: application/json" \
  -d '{"max_rpm": 30}'

# Rotate (keys:write). Idempotency-Key is required. The new key keeps the old
# key's settings. The old key keeps working for 24 hours, then expires.
curl -sS -X POST https://northerninference.ca/api/agent/v1/keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $NI_MGMT" \
  -H "Idempotency-Key: $(uuidgen)"

# Revoke a key (keys:write)
curl -sS -X DELETE https://northerninference.ca/api/agent/v1/keys/$KEY_ID \
  -H "Authorization: Bearer $NI_MGMT"

# End this credential (any scope)
curl -sS -X DELETE https://northerninference.ca/api/agent/v1/credential \
  -H "Authorization: Bearer $NI_MGMT"

Un agent peut définir le nom d'une clé, ses niveaux de confidentialité autorisés (managed_canadian_cloud pour les routes canadiennes du Niveau 3, provider_api pour le Niveau 4), sa liste de routes autorisées, ses limites de débit (max_rpm, max_tpm), son plafond de dépenses (max_budget_cents), son mode de rétention zéro des données (enforce, prompt ou allow) et, à la création, une date d'expiration. Les clés de fournisseur apportées par le client et les commutateurs d'affichage propres à chaque clé restent au titulaire, dans le portail.

7. Appeler les modèles

Utilisez la clé ni_live_ exactement comme dans le guide curl :

curl https://northerninference.ca/v1/chat/completions \
  -H "Authorization: Bearer $NI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ROUTE_ID","messages":[{"role":"user","content":"hi"}],"max_tokens":20}'

Copiez la route exacte depuis https://northerninference.ca/api/billing/models (aucune clé requise) ou GET /v1/models.

Approvisionnement

Un compte créé par un agent démarre sans crédit, et l'inférence exige un solde approvisionné. Un agent qui détient les portées de paiement peut lancer l'approvisionnement, mais le titulaire le termine toujours sur Stripe. Inférence Nordique envoie le lien Stripe au titulaire par courriel. L'agent ne reçoit jamais le lien et ne voit ni ne saisit jamais les données d'une carte. Si les paiements des agents sont désactivés sur ce service, les appels de facturation répondent 403 agent_billing_disabled et les portées de paiement ne peuvent pas être demandées.

Les portées de paiement sont billing:read (voir si un mode de paiement est configuré, ainsi que les paiements), billing:setup (commencer l'ajout d'un mode de paiement) et billing:topup (commencer un achat de crédits). Demandez celles dont vous avez besoin lorsque vous demandez l'accès; le titulaire voit chacune en langage clair.

Commencer un achat de crédits

curl -sS https://northerninference.ca/api/agent/v1/billing/topups \
  -H "Authorization: Bearer $NI_MGMT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount_cents": 2500}'

amount_cents est le montant de crédits à acheter, un nombre entier à partir de 2500 (25,00 $ CA) jusqu'à 500 $ CA par défaut. N'envoyez rien d'autre : un corps de requête contenant un champ de carte est refusé. Le titulaire reçoit un courriel indiquant les crédits, les frais de service et le total, avec un bouton pour payer sur Stripe. La réponse est 201 :

{
  "payment_id": "165d9622-8413-4ac1-9d89-22e199b6b8ca",
  "display_status": "open_unpaid",
  "session_id": "cs_live_...",
  "expires_at": "2026-10-13T03:39:38+00:00",
  "currency": "cad",
  "amount_cents": "2500",
  "fee_cents": "225",
  "charge_cents": "2725",
  "replayed": false,
  "delivery": "owner_email"
}

Les champs monétaires sont des chaînes décimales exactes. charge_cents correspond aux crédits plus les frais de service avant taxes, que Stripe ajoute sur sa page. La réponse ne contient aucun lien de paiement : n'en cherchez pas. delivery indique ce qu'est devenu le courriel :

Une nouvelle tentative avec le même Idempotency-Key et le même corps de requête renvoie 200 avec le même achat et n'envoie pas de deuxième courriel. La même clé avec un corps différent est refusée avec 409 idempotency_key_reused.

Interroger l'achat

curl -sS https://northerninference.ca/api/agent/v1/billing/topups/$PAYMENT_ID \
  -H "Authorization: Bearer $NI_MGMT"

Cet appel exige billing:read et lit les propres registres d'Inférence Nordique, jamais Stripe; vous pouvez donc l'interroger toutes les quelques secondes. display_status vaut open_unpaid tant que le titulaire n'a pas payé, puis processing, puis succeeded avec credited: true une fois les crédits ajoutés au solde. expired_unpaid signifie que le lien a pris fin sans paiement (les liens durent 60 minutes par défaut); lancez un nouvel achat si le titulaire en veut encore un. last_attempt_failed: true signifie que la carte du titulaire a été refusée et que le lien est toujours ouvert. GET /api/agent/v1/account indique ensuite le nouveau available_balance_cents.

Ajoutez un mode de paiement

curl -sS -X POST https://northerninference.ca/api/agent/v1/billing/setup-sessions \
  -H "Authorization: Bearer $NI_MGMT" \
  -H "Idempotency-Key: $(uuidgen)"

# Poll it (billing:read). status: open, processing, completed or expired.
curl -sS https://northerninference.ca/api/agent/v1/billing/setup-sessions/$SETUP_ID \
  -H "Authorization: Bearer $NI_MGMT"

Cet appel exige billing:setup et envoie au titulaire un courriel avec un bouton pour ajouter une carte sur Stripe. Ni l'agent ni Inférence Nordique ne voit le numéro de la carte, et l'ajout d'une carte ne la débite pas. La réponse et les règles de livraison sont les mêmes que pour un achat. Les agents ne peuvent pas activer la recharge automatique ni débiter une carte enregistrée : chaque achat est terminé par le titulaire.

Lire l'état de la facturation

curl -sS https://northerninference.ca/api/agent/v1/billing \
  -H "Authorization: Bearer $NI_MGMT"

Cet appel exige billing:read et affiche le solde, les conditions de recharge, les achats ouverts, les 10 derniers paiements et la carte enregistrée (marque, quatre derniers chiffres et expiration). La carte est lue en direct auprès de Stripe, dans la limite de 4 lectures par heure et par compte; pour savoir si une opération est terminée, interrogez donc les points d'accès de l'achat ou de l'ajout de carte, pas celui-ci.

Ce que le titulaire voit après Stripe

Stripe renvoie le titulaire vers https://northerninference.ca/agent-payment.html, une page temporaire qui indique si le paiement a été reçu, est en cours de traitement ou a expiré. La page est destinée au titulaire, pas à l'agent. Elle pose à Inférence Nordique une seule question sur la session Stripe et n'affiche ni montant, ni nom, ni carte. L'agent doit plutôt interroger les points d'accès ci-dessus.

Portées

Les portées de paiement ne peuvent être demandées que lorsque les paiements des agents sont activés. Sinon, la demande est refusée avec 422 scope_not_available.

Mettre fin à son propre justificatif avec DELETE /credential exige un justificatif valide, mais aucune portée particulière.

Limites et durées

Un appel limité répond 429 avec un en-tête Retry-After exprimé en secondes. Respectez-le. La désactivation des nouvelles inscriptions d'agents refuse les nouvelles demandes d'inscription, les vérifications d'état, les approbations et les récupérations avec 403 agent_registration_disabled, mais ne coupe pas un identifiant déjà émis. L'exploitant peut aussi suspendre tout l'accès des agents : chaque appel avec un identifiant ni_mgmt_ répond alors 403 agent_access_blocked jusqu'à la fin de la suspension, et l'identifiant n'est pas révoqué. Depuis une même adresse IP, une deuxième adresse courriel distincte dans un délai de 24 heures répond 429 agent_enrollment_ip_email_limit.

Erreurs

Les erreurs utilisent l'enveloppe d'erreur de la plateforme : le statut HTTP, un objet error contenant code, message, ni_request_id et ni_guidance, et le même identifiant de requête dans l'en-tête X-NI-Request-ID. Appuyez-vous sur le statut et sur error.code.

Pour les titulaires de compte

Un agent ne peut que demander. C'est vous qui décidez, et vous voyez exactement ce qu'il veut avant de décider.

• Le courriel d'approbation nomme l'agent et énumère ses portées en langage clair. Si vous ne l'attendiez pas, ignorez-le ou choisissez Refuser sur la page d'approbation. La demande expire après 24 heures.
• Approuver ne communique jamais votre mot de passe. Un nouveau compte reçoit un mot de passe que vous choisissez et les documents juridiques que vous acceptez vous-même.
• L'agent reçoit un identifiant qui peut gérer les clés API et lire le compte. Si vous approuvez aussi les autorisations de paiement, il peut demander l'ajout d'une carte ou l'achat de crédits, mais il ne peut jamais payer à votre place. Il ne peut pas appeler de modèles ni changer votre mot de passe.
• Ouvrez la page Clés API du portail et repérez Accès des agents pour voir chaque agent que vous avez approuvé et révoquer n'importe lequel d'entre eux sur-le-champ. La révocation met fin à l'accès de cet agent. Les clés qu'il a déjà créées continuent de fonctionner jusqu'à ce que vous les révoquiez sur la même page.
• Changer votre mot de passe, suspendre le compte ou le supprimer met aussi fin à tous les justificatifs d'agent.
• Un compte créé par un agent démarre sans crédit. Vous pouvez ajouter des fonds dans le portail ou, si vous avez approuvé les autorisations de paiement, l'agent peut en faire la demande : Inférence Nordique vous envoie alors le lien Stripe par courriel. Rien n'est facturé à moins que vous ne l'ouvriez et que vous ne payiez sur Stripe. L'agent ne voit jamais ce lien, et vous ne partagez jamais votre carte avec lui. Si vous ne vous attendiez pas à ce courriel, ignorez-le; le lien expire dans 60 minutes.

Pour aller plus loin

• Description OpenAPI 3.1 de /api/agent/v1/
• llms.txt, le résumé en texte brut destiné aux agents
• Appeler l'inférence avec curl et les autres guides d'intégration