Utilitzem dos tipus de claus d'API per a l'autenticació:

• Claus d'API públiques
• Claus d'API privades

Les claus d'API públiques estan destinades a crear una pàgina personalitzada d'autoallotjament per a la visualització de secrets. Totes les altres accions de l'API requereixen una clau d'API privada.

Les claus d'API públiques es poden utilitzar en scripts públics. Les claus d'API privades sempre s'han de mantenir privades.

Totes dues claus d'API contenen el tipus de clau en la pròpia clau perquè es puguin distingir fàcilment.

La clau d'API s'ha d'enviar a la capçalera Authorization: ApiKey <clau>, com ara:

Authorization: ApiKey public_key_abc...

En cas de consulta no satisfactòria, la resposta tindrà un objecte error.

L'objecte conté els següents camps:

• message: el missatge d'error complet, per exemple "El text xifrat no pot estar en blanc"
• field: el camp sobre el qual es produeix l'error, per exemple "text_xifrat"

El codi d'estat de resposta HTTP també indicarà un error, per exemple:

• 403 Forbidden: la sol·licitud no s'ha permès, per exemple a causa d'una clau d'API no vàlida
• 404 Not Found: no s'ha trobat el secret sol·licitat

Tipus de sol·licitud: GET

Ruta de sol·licitud: https://password.link/api/secrets/<id>

Codi d'estat de consulta satisfactòria: 200 OK

Obtén el text xifrat, la part de contrasenya privada i altres detalls d'un secret. Requereix la clau d'API pública.

Aquesta consulta d'API es pot utilitzar per crear una pàgina personalitzada d'autoallotjament per a la visualització de secrets que no carregui cap script ni altre recurs del nostre servei.

Obtenir amb èxit un secret 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": "l'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

Consulteu els nostres exemples d'API.

Tipus de petició: POST

Ruta de la petició: https://password.link/api/secrets

Codi d'estat de la consulta reeixida: 201 Creat

Aquesta crida a l'API també permet afegir un adjunt al secret. Si us plau, poseu-vos en contacte amb nosaltres per obtenir més detalls.

Crea un secret encriptat.

Encriptar el secret al costat del client abans d'enviar-lo a la nostra API requereix crear una cadena JSON de text xifrat compatible amb SJCL. Si us plau, consulteu la documentació de SJCL per obtenir el format adequat de la cadena JSON i consulteu els nostres exemples d'API per veure exemples de com crear el text xifrat.

Creació de la contrasenya per encriptar el secret

La contrasenya que s'utilitza per encriptar el secret en AES ha de consistir en dues cadenes de 18 caràcters de llargada. La clau d'encriptació real serà la concatenació d'aquestes dues cadenes ("part privada" + "part pública") i es deriva de la contrasenya mitjançant SJCL utilitzant PBKDF2.

Exemple de creació de les parts privada i pública de la contrasenya:

Contrasenya: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Part privada: fkgjbnvlakwiejgutn
=> Part pública: 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ó del secret que us proporcionem, també heu de codificar en Base64 la part pública. Si utilitzeu una pàgina de visualització del secret autoallotjada, podeu utilitzar el mateix mètode o crear el vostre propi. Si us plau, consulteu els nostres exemples d'API per obtenir implementacions de referència.

Configuració necessària de SJCL AES

Heu d'utilitzar la següent configuració per AES quan encripteu el secret:

• Mode: AES-GCM (configuració SJCL: "mode:gcm")
• Mida de la clau: 256 bits (configuració SJCL: "ks:256")
• Funció de derivació de clau: PBKDF2 (per defecte a SJCL)
• Iteracions de PBKDF2: 10000 (configuració SJCL: "iter:10000")

Càrrega de la petició

{
"ciphertext": "text_xifrat",
"password_part_private": "part_privada_contrasenya",
"description": "descripció",
"message": "missatge",
"expiration": "caducitat",
"view_button": "botó_visualització",
"captcha": "captcha",
"password": "contrasenya",
"max_views": "max_visualitzacions"
}

Paràmetres de la petició

• text_xifrat: una cadena JSON de text xifrat compatible amb SJCL del secret, codificada en Base64.
• part_privada_contrasenya: la part privada de la contrasenya que s'ha utilitzat per encriptar el secret, en format Base64.
• descripció (opcional): una descripció del secret. No es pot veure quan es visualitza el secret.
• missatge (opcional): un missatge per al secret. Es mostrarà juntament amb el secret.
• caducitat (opcional): un temps de caducitat per al secret, en hores. Valors possibles: 0-350.
• botó_visualització (opcional): mostra un botó de visualització del secret en lloc de mostrar el secret immediatament després d'obrir l'enllaç. Per habilitar aquesta funció, establiu-ho a true.
• captcha (opcional): mostra un CAPTCHA senzill abans de mostrar el secret, principalment per bloquejar escanejadors automatitzats. Per habilitar aquesta funció, establiu-ho a true.
• contrasenya (opcional): una contrasenya per al secret.
• max_visualitzacions (opcional): quantes vegades es pot veure el secret. Valors possibles: 1-100.

Exemple de codi

Si us plau, consulteu els nostres exemples d'API.

Tipus de petició: GET

Ruta de la petició: https://password.link/api/secrets

Codi d'estat de la consulta reeixida: 200 OK

Obtén una llista de secrets. No conté les parts de contrasenya privades en forma de text xifrat, només IDs, descripcions i similars.

Límit i desplaçament

La quantitat màxima de secrets retornats per cada consulta està limitada a 50. Pots controlar el desplaçament amb el paràmetre de consulta opcional offset.

Per exemple, per saltar els primers 50 registres, utilitza 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": l'ID del secret,
    "created_at": quan es va crear el secret,
    "message": el missatge del secret,
    "description": la descripció del secret,
    "view_button": està habilitat el botó de visualització del secret,
    "captcha": està habilitat el CAPTCHA,
    "password": el secret té contrasenya,
    "expiration": temps d'expiració en hores,
    "expired": el secret ha expirat,
    "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'observador,
        "viewed_by_user_agent": agent d'usuari de l'observador
      }
    ]
  }
],
"metadata": {
  "secrets_total": 1,
  "secrets_usage": 1,
  "secrets_allowance": 1
}
}

Tipus de petició: DELETE

Ruta de la petició: https://password.link/api/secrets/<id>

Codi d'estat de la consulta reeixida: 200 OK

Esborra 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
}
}

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
  }
}

Tipus de sol·licitud: GET

Ruta de sol·licitud: https://password.link/api/secret_requests

Codi d'estat de la consulta reeixida.: 200 OK

Llista de sol·licituds secretes.

Limit i offset

El màxim de resultats retornats per cada consulta està limitat a 50. Podeu controlar l'offset amb el paràmetre opcional offset de la consulta.

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
  }
}

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
  }
}