Tokens de Subida Firmados

Los tokens de subida firmados son credenciales con tiempo limitado diseñadas para subidas del lado del cliente. Permiten que los navegadores y aplicaciones móviles suban archivos directamente a IPFS Ninja sin exponer tu clave API.

Un flujo típico: tu servidor genera un token firmado usando tu clave API, lo pasa al cliente, y el cliente lo usa para subir archivos. El token expira automáticamente después de la duración especificada.

Generar Token Firmado

POST /upload/signed-url

Crea un nuevo token de subida firmado.

Parámetro	Tipo	Requerido	Descripción
name	string	No	Etiqueta para el token (ej. "Subidas app móvil").
expiresIn	number	Sí	Tiempo de vida del token en segundos.

Ejemplo de solicitud

curl -X POST https://api.ipfs.ninja/upload/signed-url \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile app", "expiresIn": 3600}'

Respuesta 201 Created

{
  "token": "sup_a1b2c3d4e5f6789012345678abcdef01...",
  "tokenId": "tok_9876543210abcdef",
  "tokenPrefix": "sup_a1b2c3d4",
  "tokenName": "Mobile app",
  "expiresAt": 1711040400000
}

WARNING

El token completo solo se devuelve una vez al crearlo. Guardalo de forma segura o pasalo directamente a tu cliente.

Listar Tokens Firmados

GET /signed-tokens

Devuelve todos los tokens firmados de tu cuenta, incluyendo estadisticas de uso.

Ejemplo de solicitud

curl https://api.ipfs.ninja/signed-tokens \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta 200 OK

[
  {
    "tokenId": "tok_9876543210abcdef",
    "tokenPrefix": "sup_a1b2c3d4",
    "tokenName": "Mobile app",
    "expiresAt": 1711040400000,
    "useCount": 15,
    "lastUsedAt": 1711038600000,
    "createdAt": 1711036800000
  }
]

Revocar Token Firmado

DELETE /signed-tokens/:tokenId

Revoca inmediatamente un token firmado. Cualquier intento de subida posterior usando este token será rechazado.

Parámetro	Tipo	Requerido	Descripción
tokenId	string	Sí	El ID del token a revocar (ej. "tok_9876543210abcdef").

Ejemplo de solicitud

curl -X DELETE https://api.ipfs.ninja/signed-tokens/tok_9876543210abcdef \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta 200 OK

{
  "message": "Token revoked"
}

Usar un Token Firmado

Para subir con un token firmado, pasalo a través del encabezado Authorization con el esquema Signed:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "Authorization: Signed sup_a1b2c3d4e5f6789012345678abcdef01..." \
  -H "Content-Type: application/json" \
  -d '{"content": {"name": "example"}, "description": "Client upload"}'

El cuerpo de la solicitud y el formato de respuesta son identicos a una subida de archivo estándar.

Seguimiento de Uso

Cada vez que se usa un token firmado, el useCount se incrementa y lastUsedAt se actualiza. Puedes monitorear la actividad de los tokens mediante GET /signed-tokens.

Los tokens firmados se registran con su prefijo en el campo API_KEY_PREFIX de las analíticas. Esto significa que puedes filtrar analíticas por prefijo de token firmado de la misma manera que filtras por prefijo de clave API. Consulta Analíticas para más detalles.

Ejemplo: Subida desde el Navegador

Genera un token en tu servidor y usalo en JavaScript del lado del cliente:

// Server-side: generate a token valid for 1 hour
const res = await fetch("https://api.ipfs.ninja/upload/signed-url", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_server_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "Web form", expiresIn: 3600 })
});
const { token } = await res.json();
// Pass `token` to the client

// Client-side: upload a file using the signed token
const file = document.getElementById("fileInput").files[0];
const reader = new FileReader();
reader.onload = async () => {
  const base64 = reader.result.split(",")[1];
  const uploadRes = await fetch("https://api.ipfs.ninja/upload/new", {
    method: "POST",
    headers: {
      "Authorization": `Signed ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      content: base64,
      description: "User upload"
    })
  });
  const data = await uploadRes.json();
  console.log("Uploaded:", data.cid);
};
reader.readAsDataURL(file);