Authentication

All FileNest API requests require a Bearer token in the Authorization header.

Bearer token

curl https://filenest.drgodly.com/v1/projects \
  -H "Authorization: Bearer fn_live_abc123..."

Prefix	Type	Issued by
`fn_live_...`	Production API key	FileNest Console / IAM
`fn_test_...`	Test API key	FileNest Console / IAM
`fn_sa_...`	Service account	FileNest Console
`fn_upload_token_...`	Short-lived upload token	Your server via `/api/filenest-token`

The full key is shown exactly once. Store it in a secret manager (AWS Secrets Manager, Vault, etc.) or as an environment variable.

API keys carry a set of scopes. A request will be rejected with 403 Forbidden if the key does not have the required scope.

Scope	Required for
`files:upload`	`POST /files/upload`, `/files/multipart/*`
`files:download`	`GET /files/{id}/download`, `/versions/{id}/download`
`files:read`	`GET /files`, `GET /files/{id}`, `GET /files/{id}/versions`
`files:delete`	`DELETE /files/{id}`
`files:metadata`	`PUT/POST /files/{id}/tags`, `PATCH /files/{id}`, `/versions/{id}/restore`

Scope	Required for
`folders:read`	`GET /folders`, `GET /folders/by-path`, `GET /folders/{id}`, `GET /folders/{id}/files`
`folders:write`	`POST /folders`, `POST /folders/ensure-path`, `DELETE /folders/{id}`, `POST /files/{id}/move`

Scope	Required for
`upload_tokens:create`	`POST /upload-tokens`

Scope	Required for
`webhooks:read`	`GET /webhooks`, `GET /webhooks/{id}/deliveries`
`webhooks:write`	`POST /webhooks`, `PUT /webhooks/{id}`, `DELETE /webhooks/{id}`

Scope	Required for
`projects:read`	`GET /projects`, `GET /projects/{id}`, `GET /storage`, `GET /usage`, `GET /dashboard`
`projects:update`	`POST /projects`, `PATCH /projects/{id}`, `PUT /storage`, `POST/PUT /metadata-schemas`

Scope	Required for
`audit:read`	`GET /audit`
`compliance:manage`	Legal hold, WORM, retention policy configuration

Status	Code	Meaning
`401`	`authentication_required`	No `Authorization` header
`401`	`invalid_token`	Token not recognized or revoked
`403`	`insufficient_scope`	Token lacks the required scope

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have scope files:upload",
    "required_scope": "files:upload"
  }
}