Généralités
Nous disposons d'une API REST standard pour la gestion des secrets. Toutes les demandes et réponses utilisent le format JSON.
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 de charger des actifs 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 n'importe quel type de 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 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 afin qu'elles puissent être facilement distinguées.
La clé API doit être envoyée dans l'en-tête Authorization: ApiKey <key>, comme suit:
Authorization: ApiKey public_key_abc...
Erreurs
En cas d'échec de la requête, la réponse contiendra un objet d'erreur.
Cet objet contient les champs suivants
- message : le message d'erreur complet, par exemple "Ciphertext can't be blank" (le texte chiffré ne peut être vide)
- champ : le champ concerné par l'erreur, par exemple "ciphertext"
Le code d'état de la réponse HTTP indique également une erreur, par exemple :
- 403 Forbidden (Interdit) : 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 requête: GET
Chemin de la requête: https://password.link/api/secrets/<id>
Code d'état de la requête réussie: 200 OK
Récupérer le texte chiffré, la partie privée du mot de passe et d'autres détails d'un secret. Nécessite la clé publique de l'API.
Cette requête API peut être utilisée pour créer une page de visualisation de secret personnalisée et auto-hébergée qui ne charge aucun script ou autre actif de notre service.
La récupération d'un secret marque automatiquement sa visualisation et supprime le texte chiffré et le mot de passe privé de notre base de données, ce qui rend impossible toute nouvelle visualisation 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'identifiant du secret", "ciphertext" :"le texte chiffré du secret", "password_part_private" :"la partie privée du mot de passe du secret", "message" :"le message du secret, s'il est défini" }, "metadata" : { "secrets_total" : 1, "secrets_usage" : 1, "secrets_allowance" : 1 } }
Exemple de code
Veuillez consulter nos exemples d'API.
Créer un secret
Type de requête: POST
Chemin de la requête: 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 au secret. Veuillez nous contacter pour plus de détails.
Créer un secret crypté.
Le cryptage du secret côté client avant de l'envoyer à notre API nécessite la création d'une chaîne JSON de texte chiffré compatible avec SJCL. Veuillez vous référer à la documentation SJCL pour connaître le format correct de la chaîne JSON, et consultez nos exemples d'API pour savoir comment 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 être composé de deux chaînes de 18 caractères. La clé de chiffrement réelle sera la concaténation de ces deux chaînes ("partie privée" + "partie publique") et est 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 :
Mot de passe : fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL => Partie privée : fkgjbnvlakwiejgutn => Partie publique : FIGKEOTIRUBNAKQJRL
La partie privée doit être encodée en Base64 avant d'être envoyée à notre API. Si vous utilisez la page view secret fournie par nos soins, vous devez également encoder Base64 la partie publique. Si vous utilisez une page de secret de visual isation hébergée par vos soins, vous pouvez utiliser la même méthode ou créer la vôtre. Veuillez consulter nos exemples d'API 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 (paramètre SJCL : "mode:gcm")
- Taille de la clé: 256 bits (paramètre SJCL : "ks:256")
- Fonction de dérivation de clé : PBKDF2 (paramètre par défaut de SJCL)
- PBKDF2 itérations: 10000 (paramètre SJCL : "iter:10000")
Charge utile de la requête
{ "ciphertext": ""ciphertext"", "password_part_private": "password_part_private", "description": "description", "message": "message", "expiration": "expiration", "view_button": "view_button", "captcha": "captcha", "password": "password", "max_views": "max_views" }
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 privée du mot de passe qui a été utilisée pour chiffrer le secret, au format Base64.
- description (facultatif) : description du secret. Elle n'est pas visible lors de l'affichage du secret.
- message (facultatif) : un message pour le secret. Il sera affiché avec le secret.
- expiration (facultatif) : délai d'expiration du secret, en heures. Valeurs possibles : 0-350.
- view_button (optionnel) : affiche un bouton "view secret" au lieu d'afficher le secret immédiatement après l'ouverture du lien. Pour activer cette fonctionnalité, réglez cette valeur sur true (vrai).
- captcha (optionnel) : affiche un CAPTCHA simple avant d'afficher le secret, principalement pour bloquer les scanners automatiques. Pour activer cette fonctionnalité, réglez-la sur true.
- password (optionnel) : un mot de passe pour le secret.
- max_views (optionnel) : combien de fois le secret peut être vu. Valeurs possibles : 1-100.
Exemple de code
Veuillez consulter nos exemples d'API.
Liste des secrets
Type de requête: GET
Chemin de la requête: https://password.link/api/secrets
Code d'état de la requête réussie: 200 OK
Récupère une liste de secrets. Ne contient pas les parties privées des mots de passe, seulement les identifiants, les descriptions et autres.
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 du paramètre de requête optionnel offset.
Par exemple, pour ignorer les 50 premiers enregistrements, utilisez une requête telle que : .../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'identifiant du secret, "created_at": date de création du secret, "message": le message du secret, "description": la description du secret, "view_button": le bouton "view secret" est-il activé? "captcha": le CAPTCHA est-il activé? "password": le secret a-t-il un mot de passe? "expiration": durée d'expiration en heures, "expired": le secret a-t-il expiré? "view_times": combien de fois le secret a été vu, "max_views": le nombre maximum de fois que le secret peut être consulté, "views": [ { "viewed_at": date à laquelle le secret a été consulté, "viewed_by_ip": Adresse IP du spectateur, "viewed_by_user_agent": agent utilisateur du spectateur } ] } ], "metadata": { "secrets_total": 1, "secrets_usage": 1, "secrets_allowance": 1 } }
Supprimer le secret
Type de demande: DELETE
Chemin de la requête: https://password.link/api/secrets/<id>
Code d'état de la requête réussie: 200 OK
Suppression d'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 } }
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_to_email: envoie le lien secret créé à 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éé à l'aide de la demande de secret, en heures.
- secret_max_views: limite de visualisation pour le secret créé à l'aide de la demande de secret.
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
Liste des demandes secrètes.
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
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_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 } }