Authentication
Send your secret key in the Authorization header, from your server only.
Every request carries your secret key as a bearer token. A request without a valid key gets 401 and changes nothing.
curl https://api.submitator.com/v1/ping \
-H "Authorization: Bearer $SUBMITATOR_API_KEY"The key goes in the Authorization header only: the API reads it from nowhere else, such as the query string.
Keys
A key is a prefix, 8 letters or digits, an underscore and 43 more letters or digits:
sbm_live_8fK2qL7x_Vb3Nc8Tk3HwPm2Lr9Xz5Qa1Ws4Ed7Rf0Tg6Yh8Uj3Ik| Prefix | Mode | What it does |
|---|---|---|
sbm_live_ | Live | Works on real listings and spends real launches. Live keys come with your first purchase. |
sbm_test_ | Test | Runs every call on test data: nothing is submitted and nothing is spent. Test keys are free from the day you create your agency. |
The key decides the mode: there is no livemode parameter, and sending one returns 400 unknown_parameter. Each mode has its own projects, listings, events and webhook endpoints. An id from one mode returns 404 not_found with a key of the other.
GET /ping shows which key you sent: its key.id (such as key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW) is safe to log and to quote to support, the key itself is not.
Permissions
You choose a key's permissions when you create it, and GET /ping returns them in key.permissions.
| Permissions | What the key can do |
|---|---|
full | Read and write: create projects, launch them and spend launches. |
read_only | Read only. A call that changes data returns 403 permission_denied and changes nothing. |
A read-only key reads everything but logins: the Logins operations, and the file of a report with logins, answer it with 403 permission_denied.
Give a read-only key to anything that only reads, such as a dashboard or the job that copies statuses into your CRM. If that key leaks, it cannot spend a launch.
Create, roll and revoke
Keys live in the console, under Developers: live keys on the LIVE tab, test keys on the TEST tab. A new key is shown once: store it in your secret manager right away.
- Roll replaces a key. You choose when the old key stops working: now, in 1 hour or in 24 hours, so your servers can switch without downtime.
- Revoke stops a key at once. The console asks you to type the key's label first.
If a key leaks, roll it with "now" and deploy the new one.
Keep keys on your server
A key acts for your whole agency: it can create projects and spend launches. Keep it out of anything a person outside your team can open.
- Never put a key in a browser, a mobile app or a desktop app. The API sends no CORS headers, so browser calls fail anyway; call it from your server.
- Never commit a key to a repository. Read it from an environment variable, such as
SUBMITATOR_API_KEYin these docs. - Give each server or integration its own key, so you can roll one without touching the others.
Errors
| Code | Status | When |
|---|---|---|
api_key_missing | 401 | The request has no Authorization header. |
api_key_invalid | 401 | The key is unknown, revoked or expired. |
account_suspended | 403 | Your account is suspended: reads work, writes do not. |
permission_denied | 403 | A read-only key called an operation that changes data. |
not_found | 404 | The id belongs to the other mode: a live id sent with a test key, or the other way round. |
A read-only key also gets permission_denied from the Logins operations and from the file of a report with logins.