Vérification

Vérifier des numéros

Envoyez un code à usage unique par SMS ou par appel, puis vérifiez ce que la personne a saisi. Pulsr génère le code, applique l’expiration et les limites de tentatives, et ne vous montre jamais le code lui-même.

Le fonctionnement

01Une fois : créez une application (les règles) et un modèle de message (le texte).
02À chaque fois : envoyez un code à un numéro. Vous obtenez un pinId.
03Ensuite : envoyez le code saisi par la personne avec ce pinId. Pulsr répond verified: true ou explique pourquoi non.

1. Créer une application

POST/2fa/2/applications

Une application regroupe les règles de sécurité d’un cas d’usage, comme la connexion ou la confirmation d’un paiement. Chaque réglage a une valeur par défaut : ne changez que ce dont vous avez besoin.

configuration

pinAttemptsinteger: Nombre de codes erronés tolérés avant blocage. 10 par défaut.
pinTimeToLivestring: Durée de validité d’un code, comme 10m ou 1h. 15m par défaut.
allowMultiplePinVerificationsboolean: Si un même code peut être vérifié plusieurs fois. true par défaut ; mettez false pour la connexion.
verifyPinLimitstring: Tentatives de vérification par fenêtre de temps, comme 2/4s. 1/3s par défaut.
sendPinPerPhoneNumberLimitstring: Codes envoyés à un même numéro par fenêtre. 3/1d par défaut. Votre principale protection contre la fraude au SMS pumping.
sendPinPerApplicationLimitstring: Codes envoyés par toute l’application par fenêtre. 10000/1d par défaut.

2. Créer un modèle de message

POST/2fa/2/applications/{appId}/messages

Le modèle fixe le format du code et le texte. messageText doit contenir {{pin}} ; vous pouvez ajouter vos propres variables comme {{firstName}} et les remplir à l’envoi. pinType vaut NUMERIC, ALPHA, HEX ou ALPHANUMERIC.

setup-verify.ts

// Run once, then store both IDs in your configconst app = await pulsr("POST", "/2fa/2/applications", {  name: "YourApp sign-in",  enabled: true,  configuration: {    pinAttempts: 5,    allowMultiplePinVerifications: false,    pinTimeToLive: "10m",    verifyPinLimit: "2/4s",    sendPinPerApplicationLimit: "5000/12h",    sendPinPerPhoneNumberLimit: "3/1d",  },});const appPath = `/2fa/2/applications/${app.applicationId}`;const template = await pulsr("POST", `${appPath}/messages`, {  pinType: "NUMERIC",  pinLength: 6,  messageText: "Your YourApp code is {{pin}}. It expires in 10 minutes.",  senderId: "YourApp",});console.log(app.applicationId, template.messageId);

3. Envoyer un code

POST/2fa/2/pin

send-code.ts

import { pulsr } from "./client";const pin = await pulsr("POST", "/2fa/2/pin", {  applicationId: process.env.PULSR_2FA_APP_ID,  messageId: process.env.PULSR_2FA_MESSAGE_ID,  from: "YourApp",  to: "33639981234",});// Keep pinId on the server, tied to the sign-in attempt.// Never send it to the browser.await session.set("pinId", pin.pinId);

Réponse · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "to": "33639981234",  "ncStatus": "NC_DESTINATION_REACHABLE",  "smsStatus": "MESSAGE_SENT"}

smsStatus vaut MESSAGE_SENT ou MESSAGE_NOT_SENT. Pour dicter le code lors d’un appel, envoyez le même corps à POST /2fa/2/pin/voice ; la language du modèle choisit la voix.

4. Vérifier le code

POST/2fa/2/pin/{pinId}/verify

check-code.ts

const pinId = await session.get("pinId");const result = await pulsr("POST", `/2fa/2/pin/${pinId}/verify`, {  pin: codeTypedByUser,});if (result.verified) {  // The person owns this number} else if (result.pinError !== "WRONG_PIN" || result.attemptsRemaining === 0) {  // Offer to send a new code} else {  // WRONG_PIN: let them try again}

Réponse · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "msisdn": "33639981234",  "verified": true,  "attemptsRemaining": 0}

pinError	Signification
`WRONG_PIN`	Le code ne correspond pas. `attemptsRemaining` indique le nombre d’essais restants.
`TTL_EXPIRED`	Le code a expiré. Envoyez-en un nouveau.
`NO_MORE_PIN_ATTEMPTS`	Trop de codes erronés. Envoyez-en un nouveau.

Renvoyer un code

POST/2fa/2/pin/{pinId}/resend

Le renvoi garde le même pinId et compte dans la limite par numéro. Proposez-le après une trentaine de secondes, avec l’appel vocal comme seconde option.

resend-code.ts

const pinId = await session.get("pinId");// Same pinId, a new code by SMS...await pulsr("POST", `/2fa/2/pin/${pinId}/resend`, {});// ...or read out by a voice call, for landlines and people who cannot read SMSawait pulsr("POST", `/2fa/2/pin/${pinId}/resend/voice`, {});

Bonnes pratiques

Gardez le `pinId` côté serveur, rattaché à la session ou à la tentative de connexion. Le navigateur n’envoie que le code.
Limitez votre propre endpoint par IP et par compte, en plus des limites par numéro de Pulsr, pour bloquer la fraude au SMS pumping.
Dites où part le code. Affichez le numéro avec la plupart des chiffres masqués, et laissez la personne le corriger.
Une application par cas d’usage, pour qu’un code de connexion ne puisse jamais confirmer un paiement.

1. Créer une application

POST/2fa/2/applications

configuration

pinAttemptsinteger: Nombre de codes erronés tolérés avant blocage. 10 par défaut.
pinTimeToLivestring: Durée de validité d’un code, comme 10m ou 1h. 15m par défaut.
allowMultiplePinVerificationsboolean: Si un même code peut être vérifié plusieurs fois. true par défaut ; mettez false pour la connexion.
verifyPinLimitstring: Tentatives de vérification par fenêtre de temps, comme 2/4s. 1/3s par défaut.
sendPinPerPhoneNumberLimitstring: Codes envoyés à un même numéro par fenêtre. 3/1d par défaut. Votre principale protection contre la fraude au SMS pumping.
sendPinPerApplicationLimitstring: Codes envoyés par toute l’application par fenêtre. 10000/1d par défaut.

2. Créer un modèle de message

POST/2fa/2/applications/{appId}/messages

setup-verify.ts

// Run once, then store both IDs in your configconst app = await pulsr("POST", "/2fa/2/applications", {  name: "YourApp sign-in",  enabled: true,  configuration: {    pinAttempts: 5,    allowMultiplePinVerifications: false,    pinTimeToLive: "10m",    verifyPinLimit: "2/4s",    sendPinPerApplicationLimit: "5000/12h",    sendPinPerPhoneNumberLimit: "3/1d",  },});const appPath = `/2fa/2/applications/${app.applicationId}`;const template = await pulsr("POST", `${appPath}/messages`, {  pinType: "NUMERIC",  pinLength: 6,  messageText: "Your YourApp code is {{pin}}. It expires in 10 minutes.",  senderId: "YourApp",});console.log(app.applicationId, template.messageId);

3. Envoyer un code

POST/2fa/2/pin

send-code.ts

import { pulsr } from "./client";const pin = await pulsr("POST", "/2fa/2/pin", {  applicationId: process.env.PULSR_2FA_APP_ID,  messageId: process.env.PULSR_2FA_MESSAGE_ID,  from: "YourApp",  to: "33639981234",});// Keep pinId on the server, tied to the sign-in attempt.// Never send it to the browser.await session.set("pinId", pin.pinId);

Réponse · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "to": "33639981234",  "ncStatus": "NC_DESTINATION_REACHABLE",  "smsStatus": "MESSAGE_SENT"}

smsStatus vaut MESSAGE_SENT ou MESSAGE_NOT_SENT. Pour dicter le code lors d’un appel, envoyez le même corps à POST /2fa/2/pin/voice ; la language du modèle choisit la voix.

4. Vérifier le code

POST/2fa/2/pin/{pinId}/verify

check-code.ts

const pinId = await session.get("pinId");const result = await pulsr("POST", `/2fa/2/pin/${pinId}/verify`, {  pin: codeTypedByUser,});if (result.verified) {  // The person owns this number} else if (result.pinError !== "WRONG_PIN" || result.attemptsRemaining === 0) {  // Offer to send a new code} else {  // WRONG_PIN: let them try again}

Réponse · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "msisdn": "33639981234",  "verified": true,  "attemptsRemaining": 0}

pinError	Signification
`WRONG_PIN`	Le code ne correspond pas. `attemptsRemaining` indique le nombre d’essais restants.
`TTL_EXPIRED`	Le code a expiré. Envoyez-en un nouveau.
`NO_MORE_PIN_ATTEMPTS`	Trop de codes erronés. Envoyez-en un nouveau.

Renvoyer un code

POST/2fa/2/pin/{pinId}/resend

Le renvoi garde le même pinId et compte dans la limite par numéro. Proposez-le après une trentaine de secondes, avec l’appel vocal comme seconde option.

resend-code.ts

const pinId = await session.get("pinId");// Same pinId, a new code by SMS...await pulsr("POST", `/2fa/2/pin/${pinId}/resend`, {});// ...or read out by a voice call, for landlines and people who cannot read SMSawait pulsr("POST", `/2fa/2/pin/${pinId}/resend/voice`, {});

Bonnes pratiques

Gardez le `pinId` côté serveur, rattaché à la session ou à la tentative de connexion. Le navigateur n’envoie que le code.
Limitez votre propre endpoint par IP et par compte, en plus des limites par numéro de Pulsr, pour bloquer la fraude au SMS pumping.
Dites où part le code. Affichez le numéro avec la plupart des chiffres masqués, et laissez la personne le corriger.
Une application par cas d’usage, pour qu’un code de connexion ne puisse jamais confirmer un paiement.