Authentication

Authentication

All protected endpoints require authentication. Use an API key or a session JWT (Bearer token).

Base URL

https://api.pinarkive.com/api/v3

Use this base for all API requests. Example: https://api.pinarkive.com/api/v3/files for uploads.

Headers

Required for protected routes

HeaderDescriptionExample
AuthorizationBearer token (JWT or API key)Authorization: Bearer YOUR_API_KEY
X-API-KeyAlternative to Bearer; send your API keyX-API-Key: YOUR_API_KEY

Use one of the two. Sending both is allowed; the server will accept either.

Optional

HeaderWhen to useDescription
X-Request-SourceWeb apps using BearerSet to web so the backend classifies traffic as WEB in logs. Without it, browser requests may be logged as JWT.
X-ClusterMulti-clusterOverride or target a cluster (or use cl in body/query).
Content-TypeJSON request bodiesapplication/json. Omit for multipart uploads.

API Keys

Create API keys in the dashboard (opens in a new tab) or via POST /api/v3/tokens/generate. Each key can have scopes that limit what it can do:

ScopeAllows
files:readList uploads (GET /users/me/uploads)
files:writeUpload files (POST /files) and pin by CID (POST /files/pin/:cid)
files:deleteRemove pins (DELETE /files/remove/:cid)
cluster:readList clusters and gateways (GET /users/me/clusters)

If a request is made with a token that doesn’t have the required scope, the API returns 403 with code: missing_scope and required (the scope name). See Errors.

Example: authenticated request

cURL

curl -X POST https://api.pinarkive.com/api/v3/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@image.png"

JavaScript (fetch)

const response = await fetch('https://api.pinarkive.com/api/v3/files', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.PINARKIVE_API_KEY,
  },
  body: formData,
});

JavaScript (axios)

await axios.post('https://api.pinarkive.com/api/v3/files', formData, {
  headers: {
    'X-API-Key': process.env.PINARKIVE_API_KEY,
  },
});

Next steps

Upload your first fileUpload file