Documentation   /   API

General

Disponemos de una API REST estándar para la gestión de secretos. Todas las solicitudes y respuestas utilizan el formato JSON.

Puede utilizar la API para manejar tanto el cifrado y 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ódigo

Consulte nuestros ejemplos de uso de la API.

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 la 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 la cabecera Authorization: ApiKey <key> encabezado, como:

Authorization: ApiKey public_key_abc...

Errores

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

El objeto contiene los siguientes campos

  • message: el mensaje de error completo, por ejemplo, "Ciphertext can't be blank"
  • field: el campo sobre el que trata el error, por ejemplo, "ciphertext"

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 petición: https://password.link/api/secrets/<id>

Código de estado de la consulta correcta: 200 OK


Obtiene el texto cifrado, la parte privada de la contraseña y otros detalles de un secreto. Requiere la clave pública de la API.

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

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

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

Ejemplo de consulta

curl -H "Autorización: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g

Ejemplo de respuesta

{
"data": {
  "id": "el ID del secreto",
  "texto cifrado": "el texto cifrado del secreto",
  "parte_contraseña_privada": "la parte privada dela contraseña del secreto",
  "message": "el mensaje para el secreto, si se ha establecido"
},
"metadata": {
  "secrets_total": 1
  "uso_secretos": 1,
  "secrets_allowance": 1
}
}

Ejemplo de código

Consulte nuestros ejemplos de API.

Crear secreto

Tipo de solicitud: POST

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

Código de estado de la consulta correcta: 201 Creado

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 información.


Crear un secreto cifrado.

Para cifrar el secreto del cliente antes de enviarlo a nuestra API es necesario crear una cadena JSON de texto cifrado compatible con SJCL. Consulte la documentación de SJCL para conocer el formato correcto de la cadena JSON y consulte nuestros ejemplos de API 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 de longitud. 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:

Contraseña: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Parte privada: fkgjbnvlakwiejgutn
=> Parte pública: FIGKEOTIRUBNAKQJRL

La parte privada debe codificarse en Base64 antes de enviarla a nuestra API. Si utiliza la página View Secret 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 nuestros ejemplos de API para ver implementaciones de referencia.

Configuración AES de SJCL necesaria

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

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

Carga útil de la solicitud

{
"texto cifrado": "ciphertext",
"password_part_private": "password_part_private",
"description": "description",
"message":"mensaje",
"expiration": "expiración",
"view_button": "view_button",
"captcha": "captcha",
"password": "password",
"max_views": "max_views"
}

Parámetros de solicitud

  • ciphertext: Una cadena JSON de texto cifrado compatible con SJCL del secreto, codificada en Base64.
  • password_part_private: la parte privada de la contraseña que se utilizó para cifrar el secreto, en formato Base64.
  • description (opcional): una descripción del secreto. No se puede ver cuando se visualiza el secreto.
  • message (opcional): un mensaje para el secreto. Se mostrará junto con el secreto.
  • expiración (opcional): tiempo de expiración del 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 opción, configúrela como true.
  • captcha (opcional): muestra 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 de secretos

Tipo de petición: GET

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

Código de estado de la consulta correcta: 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 de consulta opcional offset.

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

Ejemplo de consulta

curl -H "Autorización: ApiKey private_key_abcd" https://password.link/api/secrets

Ejemplo de respuesta

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

Borrar secreto

Tipo de solicitud: DELETE

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

Código de estado de la consulta correcta: 200 OK


Borrar un secreto.

Ejemplo de consulta

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

Ejemplo de respuesta

{
"data": null
"metadata": {
  "secrets_total": 1
  "uso_secretos": 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


Lista de peticiones secretas.

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