Auth Scopes

API keys are created with specific scopes that control which endpoints they can access. When creating a key in the Parsify Dashboard, select only the scopes required for your use case.

Available Scopes

Scope	Description	Required For
`documents:read`	List and retrieve documents	`GET /api/v1/documents/`
`documents:write`	Upload documents	`POST /api/v1/documents/upload/`
`jobs:read`	List and retrieve extraction jobs	`GET /api/v1/jobs/`
`jobs:write`	Create and resubmit extraction jobs	`POST /api/v1/jobs/`
`migrations:read`	Read migrations and runs	`GET /api/v1/payroll-migrations/`
`migrations:write`	Create and update migrations and runs	`POST /api/v1/payroll-migrations/`
`validations:read`	Read validation reports	`GET .../validations/`
`validations:write`	Create validation reports	`POST .../validations/`
`providers:read`	Read provider list	Public — no scope needed

Scope Naming Convention

Scopes follow the pattern resource:action:

read grants access to GET endpoints (list and retrieve).
write grants access to POST, PUT, PATCH, and DELETE endpoints.

A write scope does not imply read access. If your integration needs to both upload and list documents, include both documents:read and documents:write.

Scope Errors

If your API key is missing a required scope, the API returns a 403 Forbidden response:

{
  "detail": "You do not have permission to perform this action."
}

See Error Handling for more on error responses.

Best Practices

Least privilege — Grant only the scopes each key needs.
Separate keys per service — If multiple services call the API, create a dedicated key for each with its own minimal scopes.
Rotate regularly — Delete and recreate keys on a regular cadence.

Error Handling Pagination