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

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

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.

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.

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

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