Authentication
Every request carries an API key:
Authorization: Bearer pw_live_...Owners and admins of an account create and revoke keys on its account page (people only: a key can’t make keys). A key’s secret is shown once; we keep only a hash, so a lost key can’t be recovered. Revoke it and create another. An account can have 50 active keys.
| Prefix | Mode | What it does |
|---|---|---|
pw_live_ |
live | Real projects, processed by our studio pipeline and paid with the account’s credits. |
pw_test_ |
test | Simulated projects: validated and priced like live ones, never processed, never charged. See Test mode. |
A key sees only its own mode’s projects, events and webhook endpoints: live and test never mix.
Permissions
Section titled “Permissions”A key holds some of these permissions, chosen when it’s made. It can’t have one its creator doesn’t have.
| Permission | Allows |
|---|---|
account:read |
The account’s balance, credit history, purchases, and credits.* events. |
projects:read |
Reading projects and downloading their outputs; the events feed. |
projects:write |
Creating projects, uploading, submitting test projects, cancelling, deleting files. |
credits:spend |
Submitting live projects (they spend credits). Live keys only. |
billing:purchase |
Buying credits with the account’s saved card. Live keys only. |
webhooks:manage |
Webhook endpoints and their deliveries. |
A request that needs a permission the key doesn’t have gets 403 with code missing_scope. A test key asking to
spend or buy gets 403 test_mode.
Keys follow the person who made them
Section titled “Keys follow the person who made them”A key never does more than its creator can do now. If the creator’s role on a team changes, the key loses what
the new role can’t do; if they leave the team or their user is disabled, the key stops working (401). Keys for a
long-running integration are best made by an owner.
Checking a key
Section titled “Checking a key”curl https://api.podsworth.com/v1/me -H "Authorization: Bearer $PODSWORTH_KEY"{ "accountId": "acc_…", "actorType": "api_key", "actorId": "key_…", "mode": "test", "scopes": ["projects:read", "projects:write"] }scopes are the permissions the key has right now.