Docs - API

Général

Nous disposons d'une API REST standard pour la gestion des secrets. Toutes les requêtes et réponses utilisent l'élément JSON format.

Vous pouvez utiliser l'API pour gérer à la fois le cryptage et le décryptage du secret en dehors de notre service, sans avoir besoin de charger des ressources de notre part. Cela vous permet également d'utiliser n'importe quelle méthode de livraison pour la partie mot de passe public (la moitié du mot de passe qui est utilisée pour dériver la clé de cryptage du secret) et de créer fondamentalement n'importe quelle configuration personnalisée pour visualiser le secret.

Exemples de code

Veuillez consulter nos exemples d'API pour savoir comment utiliser l'API.

Authentification

Nous utilisons deux types de clés API pour l'authentification :

• Clés d'API publiques
• Clés d'API privées

Les clés API publiques sont destinées à la création d'une page view secret personnalisée et auto-hébergée. Toutes les autres actions API nécessitent une clé API privée.

Les clés d'API publiques peuvent être utilisées dans des scripts publics. Les clés d'API privées doivent toujours rester privées.

Les deux clés API contiennent le type de la clé dans la clé elle-même, ce qui permet de les distinguer facilement.

La clé API doit être envoyée dans le fichier Authorization: ApiKey <key> l'en-tête, comme :

Authorization: ApiKey public_key_abc...

Erreurs

Si la demande n'aboutit pas, la réponse comportera un message de type error objet.

L'objet contient les champs suivants :

• message : le message d'erreur complet, par exemple "Ciphertext can\n't be blank"
• champ : le champ sur lequel porte l'erreur, par exemple "ciphertext" (texte chiffré)

Le code d'état de la réponse HTTP indiquera également une erreur, par exemple :

• 403 Forbidden : la demande n'a pas été autorisée, par exemple en raison d'une clé API non valide
• 404 Not Found : le secret demandé n'a pas été trouvé

Voir le secret

Type de demande : GET

Chemin d'accès à la demande : https://password.link/api/secrets/<id>

Code d'état de la requête réussie : 200 OK

Permet d'obtenir le texte chiffré, la partie privée du mot de passe et d'autres détails d'un secret. Nécessite le public Clé API.

Cette requête API peut être utilisée pour créer une page secrète personnalisée auto-hébergée qui ne charge pas de scripts ou d'autres ressources de notre service.

L'obtention d'un secret marque automatiquement sa consultation et supprime donc le texte chiffré et le mot de passe privé de notre base de données, ce qui rend impossible une nouvelle consultation du secret.

Paramètres requis

• id: l'identifiant du secret, par exemple dT5g

Exemple de requête

curl -H "Authorization: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g

Exemple de réponse

{
        "data": {
          "id": "l'ID du secret",
          "ciphertext": "le texte chiffré du secret",
          "password_part_private": "le mot de passe privé qui fait partie du secret",
          "message": "le message pour le secret, s'il est défini"
        },
        "metadata": null
      }

Exemple de code

Veuillez consulter nos exemples d'API.

Créer un secret

Type de demande : POST

Chemin d'accès à la demande : https://password.link/api/secrets

Code d'état de la requête réussie : 201 Created

Cet appel API permet également d'ajouter une pièce jointe chiffrée au secret.

Créer un secret crypté.

Le chiffrement du secret côté client avant son envoi à notre API nécessite la création d'une chaîne JSON de chiffrement compatible SJCL. Veuillez vous référer à <a href=\"https://github.com/bitwiseshiftleft/sjcl\">Documentation SJCL</a> pour le format approprié de la chaîne JSON, et voir notre <a href=\"/p/docs/api/examples\">Exemples d'API</a> pour des exemples sur la façon de créer le texte chiffré.

Création du mot de passe pour le cryptage du secret

Le mot de passe utilisé pour crypter le secret dans AES doit consister en deux chaînes de 18 caractères. La clé de chiffrement proprement dite sera la concaténation de ces deux chaînes ("partie privée" + "partie publique") et sera dérivée du mot de passe par SJCL à l'aide de PBKDF2.

Exemple de création des parties privée et publique du mot de passe :

Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
        => Private part: fkgjbnvlakwiejgutn
        => Public part: FIGKEOTIRUBNAKQJRL

La partie privée doit être encodée en Base64 avant d'être envoyée à notre API. Si vous utilisez la page de secret de visualisation que nous vous fournissons, vous devez également encoder Base64 la partie publique. Si vous utilisez une page de secret de visualisation hébergée par vos soins, vous pouvez utiliser la même méthode ou créer votre propre page. Veuillez consulter notre <a href=\"/p/docs/api/examples\">Exemples d'API</a> pour des implémentations de référence.

Paramètres SJCL AES requis

Vous devez utiliser les paramètres suivants pour AES lors du cryptage du secret :

• Mode : AES-GCM (Réglage SJCL : "mode:gcm")
• Taille de la clé : 256 bits (Réglage SJCL : "ks:256")
• Fonction de dérivation de clé : PBKDF2 (SJCL par défaut)
• PBKDF2 itérations : 10000 (Réglage SJCL : "iter:10000")

Charge utile de la demande

{
        "ciphertext": "ciphertext",
        "password_part_private": "password_part_private",
        "password_part_public": "password_part_public",
        "description": "description",
        "message": "message",
        "expiration": "expiration",
        "view_button": "view_button",
        "captcha": "captcha",
        "password": "password",
        "max_views": "max_views",
        "email_to": "recipient@example.com",
        "otp_email_recipient": "recipient@example.com",
        "otp_sms_recipient": "+358401234567",
        "allowed_ips": "192.0.2.10,198.51.100.0/24",
        "allowed_locations": ["FI", "SE"],
        "available_after": "2026-07-02T12:00:00Z",
        "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
        "reply_enabled": true,
        "ack_required": true,
        "ack_mode": "ack_mode",
        "ack_phrase": "ack_phrase",
        "ack_disclosure_text": "ack_disclosure_text",
        "ack_collect_name": true,
        "ack_name_required": true,
        "ack_collect_org": true,
        "attachment": {
          "file_name": "file_name",
          "file_type": "file_type",
          "file_size": "file_size"
        }
      }

Paramètres de la demande

• ciphertext: Une chaîne JSON de texte chiffré compatible SJCL du secret, encodée en Base64.
• password_part_private: la partie du mot de passe privé qui a été utilisée pour crypter le secret, en Base64.
• password_part_public (facultatif): la partie publique du mot de passe, en Base64. Requis uniquement lors de l'utilisation de email_to afin que l'API puisse envoyer par e-mail le lien du Secret hébergé.
• description (facultatif): une description du secret. Ne peut être vu lors de la visualisation du secret.
• message (facultatif): un message pour le secret. Sera affiché le long du secret.
• expiration (facultatif): un délai d'expiration du secret, en heures. Valeurs possibles : 1-500.
• view_button (facultatif): afficher un bouton "Voir le secret" au lieu d'afficher le secret immédiatement après l'ouverture du lien. Pour activer cette fonctionnalité, définissez la valeur suivante true.
• captcha (facultatif): afficher un CAPTCHA simple avant de montrer le secret, principalement pour bloquer les scanners automatiques. Pour activer cette fonctionnalité, définissez ceci à true.
• password (facultatif): un mot de passe pour le secret.
• max_views (facultatif): le nombre de fois que le secret peut être visualisé. Valeurs possibles : 1-100.
• email_to (facultatif): destinataires e-mail séparés par des virgules qui doivent recevoir le lien du Secret créé. Requiert password_part_public.
• otp_email_recipient (facultatif): adresse e-mail qui reçoit un mot de passe à usage unique. Lorsqu'elle est définie, le destinataire doit saisir le code envoyé par e-mail avant de pouvoir voir le Secret.
• otp_recipient (facultatif): accepté comme alias de otp_email_recipient. Préférez otp_email_recipient pour les nouvelles intégrations.
• otp_sms_recipient (facultatif): numéro de téléphone qui reçoit un mot de passe à usage unique par SMS, au format international commençant par + et sans espaces.
• allowed_ips (facultatif): adresses IP ou plages CIDR séparées par des virgules autorisées à voir le Secret.
• allowed_locations (facultatif): tableau de codes pays ISO 3166-1 alpha-2 autorisés à voir le Secret.
• available_after (facultatif): date et heure avant lesquelles le Secret ne peut pas être affiché.
• secret_folder_id (facultatif): ID d'un dossier de Secrets existant appartenant à l'utilisateur de la clé API.
• reply_enabled (facultatif): activer une réponse à usage unique du destinataire après l'affichage du Secret.
• ack_required (facultatif): exiger la confirmation du destinataire avant que le Secret puisse être affiché.
• ack_mode (facultatif): mode de confirmation. Utilisez checkbox ou phrase.
• ack_phrase (requis lorsque ack_required est vrai et ack_mode est phrase): phrase que le destinataire doit saisir.
• ack_disclosure_text (facultatif): texte de divulgation affiché au destinataire, jusqu'à 500 caractères.
• ack_collect_name (facultatif): recueillir le nom du destinataire avec la confirmation.
• ack_name_required (facultatif): exiger le nom du destinataire. Cela active aussi ack_collect_name.
• ack_collect_org (facultatif): recueillir l'organisation du destinataire avec la confirmation.
• attachment (facultatif): métadonnées pour une pièce jointe chiffrée. Nécessite un plan actif. Le fichier chiffré est téléversé séparément après la création du secret.
• attachment.file_name (obligatoire lorsqu'une pièce jointe est fournie): le nom de fichier d'origine affiché au destinataire.
• attachment.file_type (obligatoire lorsqu'une pièce jointe est fournie): le type MIME d'origine, par exemple text/plain ou application/pdf.
• attachment.file_size (obligatoire lorsqu'une pièce jointe est fournie): la taille d'origine non chiffrée du fichier en octets.

Les paramètres de Secrets d'équipe peuvent désactiver, rendre obligatoires ou imposer des valeurs par défaut pour les options de Secret prises en charge. L'API applique ces règles d'équipe lors de la création d'un Secret.

Téléverser une pièce jointe

Le téléversement d'une pièce jointe se fait en deux étapes : créez d'abord le secret avec les métadonnées de la pièce jointe, puis chiffrez et téléversez la charge utile chiffrée vers l'URL de téléversement renvoyée.

Le contenu du secret et le contenu de la pièce jointe sont chiffrés séparément. Le texte chiffré du secret est constitué de données AES-GCM compatibles SJCL, encodées en Base64. La pièce jointe est chiffrée avec des données AES-GCM compatibles Web Crypto, puis encodée en Base64.

Le mot de passe de chiffrement de la pièce jointe est la partie privée brute du mot de passe concaténée avec la partie publique brute du mot de passe : <raw private password part> + <raw public password part>.

Lorsqu'une pièce jointe est incluse, la réponse de création du secret contient une cible de téléversement dans data.attachment.upload:

{
        "data": {
          "id": "dT5g",
          "attachment": {
            "file_name": "example.txt",
            "upload": {
              "url": "/api/secrets/dT5g/attachment",
              "fields": {},
              "metadata": {}
            }
          }
        },
        "metadata": {}
      }

Les URL de téléversement hébergées sur Password.link incluent un objet fields vide. Les URL de téléversement vers un stockage direct, comme les URL S3 pré-signées, renvoient les champs de signature dans metadata.

Avant le chiffrement, représentez le fichier sous forme d'URL de données : data:<mime-type>;base64,<base64 file bytes>.

Chiffrez cette chaîne d'URL de données avec AES-GCM en utilisant PBKDF2-SHA256, 10000 itérations, une clé dérivée de 256 bits, un sel aléatoire de 16 octets et un IV aléatoire de 12 octets. Stockez la charge utile chiffrée de la pièce jointe comme un objet JSON contenant cipher, iv et salt, puis encodez la chaîne JSON en Base64.

{
        "cipher": "binary string",
        "iv": "binary string",
        "salt": "binary string"
      }

Téléversez le JSON chiffré encodé en Base64 comme text/plain avec multipart/form-data vers l'URL renvoyée upload.url. Ajoutez toutes les paires upload.metadata ou upload.fields clé/valeur renvoyées aux données du formulaire avant d'ajouter le fichier chiffré. Le champ du fichier chiffré doit être nommé file.

Pour les URL de téléversement Password.link, incluez la même clé API privée dans l'en-tête Authorization: ApiKey <key>. Les URL de téléversement direct vers le stockage, comme les URL S3 présignées, ne doivent recevoir que les champs de formulaire renvoyés et le champ file chiffré.

La réponse de création de secret de l'API renvoie une cible de téléversement de pièce jointe pour le paramètre unique attachment . Les limites de taille des pièces jointes dépendent de l'allocation du compte ou de l'équipe, et le téléversement chiffré est plus volumineux que le fichier d'origine car le fichier est converti en Base64 et chiffré.

Exemple de code

Veuillez consulter nos exemples d'API.

Confirmer le Secret

Type de demande : POST

Chemin d'accès à la demande : https://password.link/api/secrets/<id>/acknowledge

Code d'état de la requête réussie : 200 OK

Envoyer la confirmation du destinataire pour un Secret créé avec ack_required. Requiert la public clé API et renvoie les mêmes données de Secret que Voir le Secret lorsque la confirmation est valide.

Si une confirmation est requise, GET /api/secrets/<id> renvoie 403 Forbidden avec secret_status défini sur ack_required jusqu'à ce que ce point de terminaison soit utilisé.

Les charges utiles de confirmation invalides ou incomplètes renvoient aussi 403 Forbidden. Elles ne sont pas renvoyées comme erreurs de validation.

Paramètres de la demande

• ack_confirmed: défini sur true pour la confirmation par case à cocher.
• ack_phrase: requis pour la confirmation par phrase, et doit correspondre à la phrase configurée pour le Secret.
• ack_signer_name: nom du destinataire, requis lorsque la collecte du nom est activée et marquée comme obligatoire.
• ack_signer_org: organisation du destinataire, enregistrée lorsque la collecte de l'organisation est activée.

Exemple de requête

curl -H "Authorization: ApiKey public_key_abcd" \
          -H "Content-Type: application/json" \
          -X POST https://password.link/api/secrets/dT5g/acknowledge \
          -d '{"ack_confirmed":true,"ack_signer_name":"Jane Doe"}'

Exemple de réponse

{
        "data": {
          "id": "l'ID du secret",
          "ciphertext": "le texte chiffré du secret",
          "password_part_private": "le mot de passe privé qui fait partie du secret",
          "message": "le message pour le secret, s'il est défini"
        },
        "metadata": null
      }

Secrets de liste

Type de demande : GET

Chemin d'accès à la demande : https://password.link/api/secrets

Code d'état de la requête réussie : 200 OK

Récupère une liste de secrets. Cette liste ne contient pas les parties privées des mots de passe chiffrés, mais uniquement les identifiants, les descriptions et autres éléments similaires.

Limite et décalage

Le nombre maximum de secrets renvoyés pour chaque requête est limité à 50. Vous pouvez contrôler le décalage à l'aide de l'option offset paramètre de requête.

Par exemple, pour ignorer les 50 premiers enregistrements, utilisez une requête comme celle-ci : .../api/secrets?offset=50

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secrets

Exemple de réponse

{
        "data": [
          {
            "id": l'ID du secret,
            "created_at": la date de création du secret,
            "message": le message pour le secret,
            "description": la description du secret,
            "view_button": le bouton "voir le secret" est-il activé ?,
            "captcha": le CAPTCHA est-il activé ?,
            "password": le secret a-t-il un mot de passe ?,
            "expiration": délai d'expiration en heures,
            "expired": le secret a expiré,
            "view_times": combien de fois le secret a été visionné,
            "max_views": le nombre maximum de fois que le secret peut être visualisé,
            "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "views": [
              {
                "viewed_at": un horodatage de la date à laquelle le secret a été consulté,
                "viewed_by_ip": Adresse IP de l'observateur,
                "viewed_by_user_agent": l'agent utilisateur du spectateur
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Mettre à jour le Secret

Type de demande : PATCH

Chemin d'accès à la demande : https://password.link/api/secrets/<id>

Code d'état de la requête réussie : 204 No Content

Mettre à jour les paramètres et métadonnées pris en charge d'un Secret existant. Requiert la privée clé API. PATCH ne remplace pas le contenu chiffré du Secret, ne renvoie pas les e-mails de livraison et ne crée pas de métadonnées d'envoi de pièce jointe. Utilisez Créer un Secret pour le ciphertext, les parties du mot de passe, la livraison du lien et les pièces jointes.

Paramètres de la demande

• description, message, expiration, max_views, view_button, captcha, password: même signification que dans Créer un Secret.
• otp_email_recipient, otp_recipient, otp_sms_recipient: même signification que dans Créer un Secret.
• allowed_ips, allowed_locations, available_after: même signification que dans Créer un Secret.
• secret_folder_id, reply_enabled: même signification que dans Créer un Secret.
• ack_required, ack_mode, ack_phrase, ack_disclosure_text, ack_collect_name, ack_name_required, ack_collect_org: même signification que dans Créer un Secret.

ciphertext, password_part_private, password_part_public, email_to et les métadonnées de pièce jointe sont réservées à la création. Elles sont ignorées par PATCH.

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" \
          -H "Content-Type: application/json" \
          -X PATCH https://password.link/api/secrets/dT5g \
          -d '{"description":"Updated description","otp_email_recipient":"recipient@example.com"}'

Supprimer le secret

Type de demande : DELETE

Chemin d'accès à la demande : https://password.link/api/secrets/<id>

Code d'état de la requête réussie : 200 OK

Supprimer un secret.

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" \\
          -X DELETE https://password.link/api/secrets/dT5g

Exemple de réponse

{
        "data": null,
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Dossiers secrets

Les points de terminaison de l'API des dossiers de Secrets requièrent la privée Clé API.

Créer un dossier de Secrets

Type de demande : POST

Chemin d'accès à la demande : https://password.link/api/secret_folders

Code d'état de la requête réussie : 201 Created

• name: nom du dossier.
• description (facultatif): description du dossier.

Exemple de réponse

{
        "data": {
          "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702"
        },
        "metadata": {
          "secrets_total":70,
          "secrets_usage":25,
          "secrets_allowance":100,
          "secret_requests_total":10,
          "secret_requests_allowance":100
        }
      }

Lister les dossiers de Secrets

Type de demande : GET

Chemin d'accès à la demande : https://password.link/api/secret_folders

Code d'état de la requête réussie : 200 OK

Exemple de réponse

{
        "data": [
          {
            "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "name": "Clients",
            "description": "Client credentials",
            "created_at": "2026-07-02T10:00:00.000Z",
            "updated_at": "2026-07-02T10:00:00.000Z"
          }
        ],
        "metadata": {
          "secrets_total":70,
          "secrets_usage":25,
          "secrets_allowance":100,
          "secret_requests_total":10,
          "secret_requests_allowance":100
        }
      }

Mettre à jour le dossier de Secrets

Type de demande : PATCH

Chemin d'accès à la demande : https://password.link/api/secret_folders/<id>

Code d'état de la requête réussie : 204 No Content

Supprimer le dossier secret

Type de demande : DELETE

Chemin d'accès à la demande : https://password.link/api/secret_folders/<id>

Code d'état de la requête réussie : 200 OK

Créer une demande de secret

Type de demande: POST

Chemin de la demande: https://password.link/api/secret_requests

Code d'état de la requête réussie: 201 Created

Créer une nouvelle demande secrète.

Paramètres de la demande

• description: description de la demande secrète.
• message: pour le visualisateur de demandes secrètes.
• expiration: le délai d'expiration de la demande secrète, en heures.
• limit: la limite d'utilisation de la demande secrète.
• send_request_to_email: envoie le lien de demande de secret créé à l'adresse électronique indiquée.
• send_request_to_sms: envoyer le lien de Secret Request créé au numéro de téléphone indiqué.
• send_to_email: envoie le lien secret créé à l'aide de la demande de secret à l'adresse électronique indiquée.
• secret_description: description du secret créé à l'aide de la demande de secret.
• secret_message: pour le secret créé à l'aide de la demande de secret.
• secret_expiration: le délai d'expiration du secret créé à l'aide de la demande de secret, en heures.
• secret_password: mot de passe pour le Secret créé avec la Secret Request.
• secret_max_views: limite de visualisation pour le secret créé à l'aide de la demande de secret.
• template_id: ID du modèle de demande à utiliser.
• secret_allowed_emails: adresses e-mail ou domaines séparés par des virgules autorisés à ouvrir les Secrets créés avec cette Secret Request.
• secret_allowed_ips: adresses IP ou plages CIDR séparées par des virgules autorisées à ouvrir les Secrets créés avec cette Secret Request.

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" \
        -H "Content-Type: application/json" -X POST https://password.link/api/secret_requests

Exemple de réponse

{
        "data": {
          "id":"5e976e6e-d205-4f58-8df9-5ac0048bc702"
        },
        "metadata": {
          "secrets_total":70,
          "secrets_usage":25,
          "secrets_allowance":100,
          "secret_requests_total":10,
          "secret_requests_allowance":100
        }
      }

Liste des demandes secrètes

Type de demande: GET

Chemin de la demande: https://password.link/api/secret_requests

Code d'état de la requête réussie: 200 OK

Limite et décalage

Le nombre maximum de résultats renvoyés pour chaque requête est limité à 50. Vous pouvez contrôler le décalage à l'aide du paramètre de requête facultatif offset.

Par exemple, pour ignorer les 50 premiers enregistrements, utilisez une requête comme celle-ci : .../api/secret_requests?offset=50

La réponse de liste n'inclut pas secret_allowed_emails ou secret_allowed_ips.

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secret_requests

Exemple de réponse

{
        "data":[
          {
            "id":"5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "description":"example",
            "message":"example",
            "expiration":3,
            "limit":1,
            "send_request_to_email":"request-recipient@example.com",
            "send_request_to_sms":"+358401234567",
            "send_to_email":"example@example.com",
            "secret_description":"example",
            "secret_message":"example",
            "secret_expiration":"example",
            "secret_max_views":4,
            "secret_password":false,
            "template_id":null
          }
        ],
        "metadata": {
          "secrets_total":70,
          "secrets_usage":25,
          "secrets_allowance":100,
          "secret_requests_total":10,
          "secret_requests_allowance":100
        }
      }

Demande de suppression du secret

Type de demande: DELETE

Chemin de la demande: https://password.link/api/secret_requests/<id>

Code d'état de la requête réussie: 200 OK

Supprimer une demande de secret.

Exemple de requête

curl -H "Authorization: ApiKey private_key_abcd" \
      -X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702

Exemple de réponse

{
        "data": null,
        "metadata": {
          "secrets_total":70,
          "secrets_usage":25,
          "secrets_allowance":100,
          "secret_requests_total":10,
          "secret_requests_allowance":100}
      }