Authentication
API keys
An API key acts for your account, not for the person who created it: a key keeps working when that colleague leaves, and records it creates name no person. Create one key per backend, script or automation, so you can revoke them one by one.
Create keys in the web app under Settings › API keys. If you logged in more than 10 minutes ago, Ghostpull asks for a code from your email first. The key is shown once, right after you create it. Store it in your password manager or your server's secrets; Ghostpull keeps only a hash and cannot show it again. A lost key is revoked and replaced.
Send it with every call:
- bash / zsh
- fish
- PowerShell
curl "$GHOSTPULL_URL/api/v1/media/assets" -H "x-api-key: $GHOSTPULL_API_KEY"
curl "$GHOSTPULL_URL/api/v1/media/assets" -H "x-api-key: $GHOSTPULL_API_KEY"
curl.exe "$env:GHOSTPULL_URL/api/v1/media/assets" -H "x-api-key: $env:GHOSTPULL_API_KEY"
Only the x-api-key header works; never put a key in a URL, and never into
code that runs in a browser.
Permissions
A key may only call what its permissions allow. Each operation in the API reference names the permission it needs.
| Permission | Allows |
|---|---|
addons:read | List the Addons the account can run, with their inputs and price. |
media:read | List and read every asset in the account's library, with download links. |
media:upload | Upload images and videos into the account's library. |
runs:read | Follow every run of the account and read its results. |
A permission covers all of the account's data, not only what the key created. Select all gives a key the permissions that exist today; a permission added later is never on an existing key until you add it.
Expiry and revoking
Every key gets an expiry when it is created: a period, a date, or Forever. An expired key stops working and has to be replaced.
Revoking a key stops its calls at once. Runs it already started finish, and download links and open streams it already got run until they expire or close.