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": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
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 au secret. Veuillez nous contacter pour plus de détails.
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",
"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 du mot de passe privé qui a été utilisée pour crypter le secret, en Base64.
- 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 : 0-350.
- 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.
Exemple de code
Veuillez consulter nos exemples d'API.
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é,
"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
}
}
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
}
}
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_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éé à 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
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}
}