Calling the API from a browser

https://api.ipfs.ninja allows requests from any origin (Access-Control-Allow-Origin: *), so you can build backendless apps that call our REST API directly from browser JavaScript. Authentication is unchanged — every request still needs a valid X-Api-Key header. If you're going to expose an API key in browser code, treat it as public (rotate on schedule, don't ship it with admin rights). For an alternative made for browser-facing use, see gateway tokens.

Authentication

The API supports three authentication methods depending on your use case.

API Key

For server-side integrations. Generate a key from your API Keys page and pass it via the X-Api-Key header:

X-Api-Key: bws_a1b2c3d4e5f6...

API keys have full access to all API endpoints — upload, delete, list files, manage settings. Never expose them in client-side code.

TIP

API keys expire 1 year after creation (expiresAt in the create/list response). Create a new key before the old one expires; you can create multiple keys and revoke them individually.

Alternate: API key via Authorization header

For tooling that only supports a single Authorization header (e.g. generic IPFS Pinning Services API clients), you can present your API key as a Bearer token instead:

Authorization: Bearer bws_a1b2c3d4e5f6...

This behaves identically to X-Api-Key — same key, same permissions. X-Api-Key remains the primary/recommended method for new integrations.

JWT Bearer Token

For the web dashboard and Cognito-authenticated sessions. Pass the token via the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

JWT tokens are issued by our authentication service when a user signs in through the IPFS Ninja dashboard. They expire automatically and are not intended for direct API integrations — use API keys instead.

Signed Upload Token

For client-side uploads without exposing your API key. Pass the token via the Authorization header:

Authorization: Signed eyJ0b2tlbklkIjoiOWY4YzFhMmUtNGIzZC00ZTVmLThhOWItMWMyZDNlNGY1YTZiIiwi...

Signed tokens are time-limited and scoped to upload operations only. They are safe to embed in browser or mobile applications. Generate them from your server using POST /upload/signed-url and hand them to the client.

See Signed Tokens for details on creating, listing, and revoking signed upload tokens.