Photopurr DocsScopes
Which endpoints each key can reach
Scopes are ticked when a key is created and cannot be changed afterwards; for different scopes create another key. Revoking one key does not affect the others.
| Scope | Endpoints | Typical use |
|---|---|---|
generate:write | POST /api/v1/generate | Generate images. Spends credits |
assets:read | GET /api/file/<filename> | Download generation results and images inside image packs |
documents:read | GET /api/v1/image-pack-publications, GET /api/v1/image-pack-publications/<id> | Pull published image packs |
Calling an endpoint without its scope returns 403 insufficient_scope, with message naming the missing scope.
Common combinations
| Scenario | Tick |
|---|---|
| Script that generates in bulk and saves the files | generate:write + assets:read |
| Listing tool that pulls image packs | documents:read + assets:read |
| Generate only, review results on the website | generate:write |
Keys with read-only scopes (assets:read / documents:read) get a higher rate limit, see rate limits.
Early keys
Keys created before scopes existed have no scope record and are treated as generate:write only. For other scopes create a new key.
Resource ownership
Scopes decide which endpoints a key may call. They never change who owns the data: each key can only reach the images, sessions and image packs of its own account. Requesting someone else's resource always returns 404, not 403.
Once an account is banned, every key under it immediately returns 403 banned.
Website login
Calls made from the browser with a cookie session are not subject to scopes; that is the website itself at work. Scopes only constrain Authorization: Bearer requests.