Documentació de l'API
General
Tenim una API REST estàndard per gestionar secrets. Totes les sol·licituds i respostes utilitzen el JSON format.
Podeu utilitzar l'API per gestionar tant l'encriptació com la desencriptació del secret fora del nostre servei, sense necessitat de carregar cap actiu de la nostra part. També permet utilitzar qualsevol tipus de mètode de lliurament per a la part pública de la contrasenya (meitat de la contrasenya que s'utilitza per derivar la clau d'encriptació per al secret) i bàsicament crear qualsevol tipus de configuració personalitzada per visualitzar el secret.
Exemples de codi
Si us plau, consulteu els nostres exemples d'API sobre com utilitzar l'API.
Autenticació
Fem servir dos tipus de claus API per a l'autenticació:
- Claus API públiques
- Claus API privades
Les claus API públiques estan destinades a crear una pàgina secreta de visualització personalitzada auto-hostejada. Totes les altres accions de l'API requereixen una clau API privada.
Les claus API públiques es poden utilitzar en scripts públics. Les claus API privades sempre han de mantenir-se privades.
Ambdues claus API contenen el tipus de clau dins de la pròpia clau, de manera que es poden distingir fàcilment.
La clau API s'ha d'enviar en el Authorization: ApiKey <key> capçalera, com:
Authorization: ApiKey public_key_abc...
Errors
En cas de consulta sense èxit, la resposta tindrà un error objecte.
L'objecte conté els següents camps:
- missatge: el missatge d'error complet, per exemple "El text xifrat no pot estar buit"
- camp: el camp del qual es tracta l'error, per exemple "text xifrat"
El codi d'estat de resposta HTTP també indicarà un error, per exemple:
- 403 Prohibit: la sol·licitud no estava permesa, per exemple a causa d'una clau API no vàlida
- 404 No trobat: el secret sol·licitat no s'ha trobat
Veure Secret
Tipus de sol·licitud: GET
Camí de sol·licitud: https://password.link/api/secrets/<id>
Codi d'estat de la consulta exitosa: 200 OK
Obtenir el text xifrat, la part de contrasenya privada i altres detalls d'un secret. Requereix el públic clau API.
Aquesta consulta d'API es pot utilitzar per crear una pàgina de secret de visualització personalitzada auto-hostejada que no carrega cap script ni altres actius del nostre servei.
Obtenir un secret amb èxit el marca automàticament com a vist i, per tant, elimina el text xifrat i la part de contrasenya privada de la nostra base de dades, fent impossible veure el secret de nou.
Paràmetres requerits- id: l'id del secret, per exemple dT5g
exemple de consulta
curl -H "Authorization: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g
exemple de resposta
{
"data": {
"id": "la ID del secret",
"ciphertext": "el text xifrat del secret",
"password_part_private": "la part de contrasenya privada del secret",
"message": "el missatge per al secret, si s'ha establert"
},
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Exemple de codi
Si us plau, consulteu els nostres exemples d'API.
Crear Secret
Tipus de sol·licitud: POST
Camí de sol·licitud: https://password.link/api/secrets
Codi d'estat de la consulta exitosa: 201 Created
Aquesta crida d'API també admet l'addició d'un adjunt al secret. Si us plau, contacteu amb nosaltres per a més detalls.
Crea un secret xifrat.
Xifrar el secret al costat del client abans d'enviar-lo a la nostra API requereix crear una cadena JSON de xifrat compatible amb SJCL. Si us plau, consulteu el <a href=\"https://github.com/bitwiseshiftleft/sjcl\">Documentació de SJCL</a> per al format adequat de la cadena JSON, i consulteu els nostres <a href=\"/p/docs/api/examples\">Exemples d'API</a> per a exemples sobre com crear el xifrat.
Creant la contrasenya per xifrar el secret
La contrasenya que s'utilitza per xifrar el secret en AES ha de consistir en dues cadenes de 18 caràcters de longitud. La clau de xifrat real serà la concatenació d'aquestes dues cadenes ("part privada" + "part pública") i es deriva de la contrasenya per SJCL mitjançant PBKDF2.
Exemple de creació de les parts de contrasenya privada i pública:
Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Private part: fkgjbnvlakwiejgutn
=> Public part: FIGKEOTIRUBNAKQJRL
La part privada ha de ser codificada en Base64 abans d'enviar-la a la nostra API. Si utilitzeu la pàgina de visualització de secrets proporcionada per nosaltres, també heu de codificar en Base64 la part pública. Si utilitzeu una pàgina de visualització de secrets autohostejada, podeu utilitzar el mateix mètode o crear el vostre propi. Si us plau, consulteu les nostres <a href=\"/p/docs/api/examples\">Exemples d'API</a> per a implementacions de referència.
Configuracions SJCL AES requerides
Heu d'utilitzar les següents configuracions per a AES quan xifreu el secret:
- Mode: AES-GCM (Configuraicó SJCL:"mode:gcm")
- Mida de la clau: 256 bits (Configuraicó SJCL:"ks:256")
- Funció de derivació de claus: PBKDF2 (Por defecte de SJCL)
- Iteracions de PBKDF2: 10000 (Configuració de SJCL: "iter:10000")
Payload de la sol·licitud
{
"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"
}
Paràmetres de la sol·licitud.
- ciphertext: Una cadena JSON de xifrat compatible amb SJCL del secret, codificada en Base64.
- password_part_private: la part de contrasenya privada que es va utilitzar per xifrar el secret, en Base64.
- description (opcional): una descripció per al secret. No es pot veure quan es visualitza el secret.
- message (opcional): un missatge per al secret. Es mostrarà juntament amb el secret.
- expiration (opcional): un temps d'expiració per al secret, en hores. Valors possibles: 0-350.
- view_button (opcional): mostrar un botó de veure el secret en comptes de mostrar el secret immediatament després d'obrir l'enllaç. Per activar aquesta funció, estableix-ho a true.
- captcha (opcional): mostrar un CAPTCHA simple abans de mostrar el secret, principalment per bloquejar escàners automatitzats. Per activar aquesta funció, estableix-ho a true.
- password (opcional): una contrasenya per al secret.
- max_views (opcional): quantes vegades es pot veure el secret. Valors possibles: 1-100.
Exemple de codi
Si us plau, consulteu els nostres exemples d'API.
Llistar Secrets
Tipus de sol·licitud: GET
Camí de sol·licitud: https://password.link/api/secrets
Codi d'estat de la consulta exitosa: 200 OK
Obteniu una llista de secrets. No conté les parts de contrasenya privada dels textos xifrats, només IDs, descripcions i coses similars.
Limit i offset
La quantitat màxima de secrets retornats per a cada consulta està limitada a 50. Podeu controlar l'offset amb l'opcional offset paràmetre de consulta.
Per exemple, per saltar els primers 50 registres, utilitzeu una consulta com aquesta: .../api/secrets?offset=50
exemple de consulta
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secrets
exemple de resposta
{
"data": [
{
"id": la ID del secret,
"created_at": quan es va crear el secret,
"message": el missatge per al secret,
"description": la descripció del secret,
"view_button": està habilitat el botó de veure el secret,
"captcha": està habilitat el CAPTCHA,
"password": té el secret una contrasenya,
"expiration": temps d'expiració en hores,
"expired": ha expirat el secret,
"view_times": quantes vegades s'ha vist el secret,
"max_views": la quantitat màxima de vegades que es pot veure el secret,
"views": [
{
"viewed_at": una marca de temps de quan es va veure el secret,
"viewed_by_ip": adreça IP de l'espectador,
"viewed_by_user_agent": agent d'usuari de l'espectador
}
]
}
],
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Esborrar Secret
Tipus de sol·licitud: DELETE
Camí de sol·licitud: https://password.link/api/secrets/<id>
Codi d'estat de la consulta exitosa: 200 OK
Esborrar un secret.
exemple de consulta
curl -H "Authorization: ApiKey private_key_abcd" \\
-X DELETE https://password.link/api/secrets/dT5g
exemple de resposta
{
"data": null,
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Crea una sol·licitud de secret
Tipus de sol·licitud: POST
Ruta de sol·licitud: https://password.link/api/secret_requests
Codi d'estat de la consulta reeixida.: 201 Created
Crea una nova sol·licitud de secret.
Paràmetres de la sol·licitud.
- description: Descripció de la sol·licitud de secret.
- message: Missatge per al visualitzador de la sol·licitud de secret.
- expiration: Temps d'expiració de la sol·licitud de secret, en hores.
- limit: Límit d'ús per a la sol·licitud de secret.
- send_request_to_email: Envia l'enllaç de la sol·licitud de secret creada a l'adreça de correu electrònic proporcionada.
- send_to_email: envia l'enllaç secret creat utilitzant la sol·licitud secret a l'adreça de correu electrònic proporcionada.
- secret_description: descripció per al secret creat utilitzant la sol·licitud secret.
- secret_message: missatge per al secret creat utilitzant la sol·licitud secret.
- secret_expiration: temps d'expiració per al secret creat utilitzant la sol·licitud secret, en hores.
- secret_password: contrasenya per al secret creat utilitzant la sol·licitud secret, en hores.
- secret_max_views: límit de visualització per al secret creat utilitzant la sol·licitud secret.
exemple de consulta
curl -H "Authorization: ApiKey private_key_abcd" \
-H "Content-Type: application/json" -X POST https://password.link/api/secret_requests
exemple de resposta
{
"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
}
}
Llista de sol·licituds secretes
Tipus de sol·licitud: GET
Ruta de sol·licitud: https://password.link/api/secret_requests
Codi d'estat de la consulta reeixida.: 200 OK
Limit i offset
La quantitat màxima de resultats retornats per a cada consulta està limitada a 50. Podeu controlar l'offset amb el paràmetre de consulta opcional offset.
Per exemple, per saltar els primers 50 registres, utilitzeu una consulta com aquesta: .../api/secret_requests?offset=50
exemple de consulta
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secret_requests
exemple de resposta
{
"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
}
}
Esborra la sol·licitud secreta
Tipus de sol·licitud: DELETE
Ruta de sol·licitud: https://password.link/api/secret_requests/<id>
Codi d'estat de la consulta reeixida.: 200 OK
Esborra una sol·licitud secreta.
exemple de consulta
curl -H "Authorization: ApiKey private_key_abcd" \
-X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702
exemple de resposta
{
"data": null,
"metadata": {
"secrets_total":70,
"secrets_usage":25,
"secrets_allowance":100,
"secret_requests_total":10,
"secret_requests_allowance":100}
}