Three ways to present a token, and why all three are accepted.
## Presenting a token
Three carriers are accepted, because deployed scripts genuinely use all three
and refusing any of them would mean migration is not the single URL change we
promise.
```bash
# Conventional
Authorization: Bearer apt_XXXXXXXX_...
# Raw, which is what most FiveM resources send
Authorization: apt_XXXXXXXX_...
# Query string, for screenshot-basic calls that cannot set headers
POST /api/v1/uploads?apiKey=apt_XXXXXXXX_...
```
The scheme is matched case-insensitively, because some Lua HTTP wrappers
title-case it and at least one sends `BEARER`.
## Scopes
A token carries only the scopes you gave it. They are checked against what was
actually sent, not against the route: a video posted to an image endpoint is
still a video, and an image-only token will refuse it.
| Scope | Allows |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `upload-image` | Uploading images |
| `upload-video` | Uploading video |
| `upload-audio` | Uploading audio |
| `read-media` | Listing and fetching metadata |
| `delete-media` | Deleting over the API |
| `debug` | Query counts and cache statistics in the response meta |
| `manage-assets` | Server assets: categories, uploads, rollbacks and upload tickets. See [Server assets](/docs/guides/server-assets) |
Split them. A leaked image key that cannot upload video is a smaller problem
than one key that can do everything.
Never grant `debug` to a token that lives in a config file. It adds internal
detail to responses that a public server has no reason to expose.
## Restricting where a token works
A token can carry an IP allowlist. That narrows a leaked key to the machines
that are supposed to hold it, which is worth doing for a game server with a
fixed address.
An empty allowlist means any address, deliberately. Treating an accidentally
cleared list as "nothing allowed" would turn a slip into a total outage that
looks like a broken token rather than a configuration mistake.
## Knowing whether a key works
```bash
curl https://your-instance/api/v1/token -H "Authorization: ${APERTURE_KEY}"
```
This answers what the key may do, how much quota is left and when it was last
used. It turns "uploads are failing" into "this key has no video scope" without
anyone opening a dashboard.
## When a key leaks
Revoke it from **Tokens**. Revocation is immediate. The token row is kept rather
than deleted, so the usage history and the audit trail still point at something
real.
`last_used_at` and `last_used_ip` are recorded on every call. A key used from an
address you do not recognise is how a leak becomes visible instead of
theoretical.
Three carriers are accepted, because deployed scripts genuinely use all three
and refusing any of them would mean migration is not the single URL change we
promise.
Shell
# Conventional
Authorization: Bearer apt_XXXXXXXX_...
# Raw, which is what most FiveM resources send
Authorization: apt_XXXXXXXX_...
# Query string, for screenshot-basic calls that cannot set headers
POST /api/v1/uploads?apiKey=apt_XXXXXXXX_...
The scheme is matched case-insensitively, because some Lua HTTP wrappers
title-case it and at least one sends BEARER.
A token carries only the scopes you gave it. They are checked against what was
actually sent, not against the route: a video posted to an image endpoint is
still a video, and an image-only token will refuse it.
Scope
Allows
upload-image
Uploading images
upload-video
Uploading video
upload-audio
Uploading audio
read-media
Listing and fetching metadata
delete-media
Deleting over the API
debug
Query counts and cache statistics in the response meta
manage-assets
Server assets: categories, uploads, rollbacks and upload tickets. See Server assets
Split them. A leaked image key that cannot upload video is a smaller problem
than one key that can do everything.
Never grant debug to a token that lives in a config file. It adds internal
detail to responses that a public server has no reason to expose.
A token can carry an IP allowlist. That narrows a leaked key to the machines
that are supposed to hold it, which is worth doing for a game server with a
fixed address.
An empty allowlist means any address, deliberately. Treating an accidentally
cleared list as "nothing allowed" would turn a slip into a total outage that
looks like a broken token rather than a configuration mistake.
This answers what the key may do, how much quota is left and when it was last
used. It turns "uploads are failing" into "this key has no video scope" without
anyone opening a dashboard.
Revoke it from Tokens. Revocation is immediate. The token row is kept rather
than deleted, so the usage history and the audit trail still point at something
real.
last_used_at and last_used_ip are recorded on every call. A key used from an
address you do not recognise is how a leak becomes visible instead of
theoretical.