Documentación API

General

Disponemos de una API REST estándar para gestionar secretos. Todas las solicitudes y respuestas utilizan el método JSON formato.

Puedes utilizar la API para manejar tanto el cifrado como el descifrado del secreto fuera de nuestro servicio, sin necesidad de cargar ningún activo nuestro. También le permite utilizar cualquier tipo de método de entrega para la parte de la contraseña pública (la mitad de la contraseña que se utiliza para derivar la clave de cifrado para el secreto de) y, básicamente, crear cualquier tipo de configuración personalizada para ver el secreto.

Ejemplos de códigos

Consulte nuestros ejemplos de API para saber cómo utilizarla.

Autenticación

Utilizamos dos tipos de claves API para la autenticación:

  • Claves API públicas
  • Claves API privadas

Las claves de API públicas están pensadas para crear una página secreta de vista personalizada autoalojada. Todas las demás acciones de API requieren una clave de API privada.

Las claves API públicas pueden utilizarse en scripts públicos. Las claves API privadas deben mantenerse siempre en privado.

Ambas claves API contienen el tipo de clave en la propia clave para que puedan distinguirse fácilmente.

La clave API debe enviarse en el campo Authorization: ApiKey <key> cabecera, como:

Authorization: ApiKey public_key_abc...

Errores

En caso de consulta fallida, la respuesta tendrá un error objeto.

El objeto contiene los siguientes campos:

  • message: el mensaje de error completo, por ejemplo "Ciphertext can't be blank" (El texto cifrado no puede estar en blanco)
  • campo: el campo sobre el que se produce el error, por ejemplo, "texto cifrado"

El código de estado de la respuesta HTTP también indicará un error, por ejemplo:

  • 403 Prohibido: la solicitud no estaba permitida, por ejemplo debido a una clave de API no válida
  • 404 Not Found: no se ha encontrado el secreto solicitado

Ver Secreto

Tipo de solicitud: GET

Ruta de solicitud: https://password.link/api/secrets/<id>

Código de estado de la consulta realizada correctamente: 200 OK


Obtener el texto cifrado, la parte privada de la contraseña y otros detalles de un secreto. Requiere el público Clave API.

Esta consulta a la API se puede utilizar para crear una página secreta de vista autoalojada personalizada que no cargue ninguna secuencia de comandos ni otros activos de nuestro servicio.

Cuando se obtiene un secreto con éxito, se marca automáticamente como visto y, por lo tanto, se borra el texto cifrado y la contraseña privada de nuestra base de datos, lo que hace imposible volver a ver el secreto.

Parámetros requeridos
  • id: el id del secreto, por ejemplo dT5g

Ejemplo de consulta

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

Ejemplo de respuesta

{
        "data": {
          "id": "el ID del secreto",
          "ciphertext": "el texto cifrado del secreto",
          "password_part_private": "la parte de la contraseña privada del secreto",
          "message": "el mensaje para el secreto, si se establece"
        },
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Ejemplo de código

Consulte nuestros ejemplos de API.

Crear secreto

Tipo de solicitud: POST

Ruta de solicitud: https://password.link/api/secrets

Código de estado de la consulta realizada correctamente: 201 Created

Esta llamada a la API también permite añadir un archivo adjunto al secreto. Póngase en contacto con nosotros para obtener más detalles.


Crea un secreto encriptado.

Cifrar el secreto del lado del cliente antes de enviarlo a nuestra API requiere crear una cadena JSON de texto cifrado compatible con SJCL. Consulte el <a href=\"https://github.com/bitwiseshiftleft/sjcl\">[</a> <a href=\"/p/docs/api/examples\">Documentación SJCL</a> ] para conocer el formato adecuado de la cadena JSON, y consulte nuestro <a href=\"/p/docs/api/examples\">Ejemplos de API</a> para ver ejemplos sobre cómo crear el texto cifrado.

Crear la contraseña para cifrar el secreto

La contraseña que se utiliza para cifrar el secreto en AES debe constar de dos cadenas de 18 caracteres. La clave de cifrado real será la concatenación de estas dos cadenas ("parte privada" + "parte pública") y se obtiene a partir de la contraseña mediante SJCL utilizando PBKDF2.

Ejemplo de creación de las partes privada y pública de la contraseña:

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

La parte privada debe codificarse en Base64 antes de enviarla a nuestra API. Si utiliza la página de vista secreta que le proporcionamos, también deberá codificar en Base64 la parte pública. Si utiliza una página view secret autoalojada, puede utilizar el mismo método o crear la suya propia. Consulte nuestro <a href=\"/p/docs/api/examples\">Ejemplos de API</a> para ver implementaciones de referencia.

Ajustes necesarios de SJCL AES

Debe utilizar la siguiente configuración para AES al cifrar el secreto:

  • Modo: AES-GCM (Configuración SJCL: "mode:gcm")
  • Tamaño de la llave: 256 bits (Configuración SJCL: "ks:256")
  • Función de derivación de claves: PBKDF2 (SJCL por defecto)
  • Iteraciones PBKDF2: 10000 (Ajuste SJCL: "iter:10000")

Solicitud de carga útil

{
        "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ámetros de la solicitud

  • ciphertext: Una cadena JSON de texto cifrado compatible con SJCL del secreto, codificada en Base64.
  • password_part_private: la parte de la contraseña privada que se utilizó para cifrar el secreto, en Base64.
  • description (opcional): descripción del secreto. No se puede ver cuando se visualiza el secreto.
  • message (opcional): un mensaje para el secreto. Se mostrará a lo largo del secreto.
  • expiration (opcional): un tiempo de expiración para el secreto, en horas. Valores posibles: 0-350.
  • view_button (opcional): mostrar un botón de ver secreto en lugar de mostrar el secreto inmediatamente después de abrir el enlace. Para activar esta función, configúrela como true.
  • captcha (opcional): mostrar un simple CAPTCHA antes de mostrar el secreto, principalmente para bloquear escáneres automáticos. Para activar esta función, configúrela como true.
  • password (opcional): una contraseña para el secreto.
  • max_views (opcional): cuántas veces se puede ver el secreto. Valores posibles: 1-100.

Ejemplo de código

Consulte nuestros ejemplos de API.

Lista Secretos

Tipo de solicitud: GET

Ruta de solicitud: https://password.link/api/secrets

Código de estado de la consulta realizada correctamente: 200 OK


Obtiene una lista de secretos. No contiene las partes de contraseña privada de los ciphertexts, sólo IDs, descripciones y similares.

Límite y desplazamiento

La cantidad máxima de secretos devueltos por cada consulta está limitada a 50. Puede controlar el desplazamiento con el parámetro opcional offset parámetro de consulta.

Por ejemplo, para omitir los 50 primeros registros, utilice una consulta del tipo: .../api/secrets?offset=50

Ejemplo de consulta

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

Ejemplo de respuesta

{
        "data": [
          {
            "id": el ID del secreto,
            "created_at": cuándo se creó el secreto,
            "message": el mensaje para el secreto,
            "description": la descripción del secreto,
            "view_button": está activado el botón ver secreto,
            "captcha": está habilitado el CAPTCHA,
            "password": ¿el secreto tiene contraseña?,
            "expiration": tiempo de expiración en horas,
            "expired": ha caducado el secreto,
            "view_times": cuántas veces se ha visto el secreto,
            "max_views": el número máximo de veces que se puede ver el secreto,
            "views": [
              {
                "viewed_at": una marca de tiempo de cuándo se vio el secreto,
                "viewed_by_ip": Dirección IP del espectador,
                "viewed_by_user_agent": agente de usuario del espectador
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Borrar secreto

Tipo de solicitud: DELETE

Ruta de solicitud: https://password.link/api/secrets/<id>

Código de estado de la consulta realizada correctamente: 200 OK


Borrar un secreto.

Ejemplo de consulta

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

Ejemplo de respuesta

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

Crear solicitud secreta

Tipo de solicitud: POST

Solicitar ruta: https://password.link/api/secret_requests

Código de estado de la consulta realizada correctamente: 201 Created


Cree una nueva Solicitud Secreta.

Parámetros de la solicitud

  • description: descripción de la solicitud secreta.
  • message: para el visor de Peticiones Secretas.
  • expiration: tiempo de expiración de la Petición Secreta, en horas.
  • limit: límite de uso de la Solicitud Secreta.
  • send_request_to_email: envía el enlace de solicitud secreta creado a la dirección de correo electrónico indicada.
  • send_to_email: envía el enlace secreto creado mediante la solicitud de secreto a la dirección de correo electrónico indicada.
  • secret_description: descripción del secreto creado mediante la solicitud de secreto.
  • secret_message: para el Secreto creado mediante la Solicitud de Secreto.
  • secret_expiration: tiempo de expiración para el Secreto creado usando la Solicitud de Secreto, en horas.
  • secret_password: contraseña para el Secreto creado mediante la Solicitud de Secreto, en horas.
  • secret_max_views: límite de vistas para el Secreto creado mediante la Solicitud de Secreto.

Ejemplo de consulta

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

Ejemplo de respuesta

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

Lista de peticiones secretas

Tipo de solicitud: GET

Solicitar ruta: https://password.link/api/secret_requests

Código de estado de la consulta realizada correctamente: 200 OK


Límite y desplazamiento

La cantidad máxima de resultados devueltos por cada consulta está limitada a 50. Puede controlar el desplazamiento con el parámetro de consulta opcional offset.

Por ejemplo, para omitir los 50 primeros registros, utilice una consulta del tipo: .../api/secret_requests?offset=50

Ejemplo de consulta

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

Ejemplo de respuesta

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

Borrar solicitud secreta

Tipo de solicitud: DELETE

Solicitar ruta: https://password.link/api/secret_requests/<id>

Código de estado de la consulta realizada correctamente: 200 OK


Borrar una solicitud secreta.

Ejemplo de consulta

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

Ejemplo de respuesta

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