Authentication
Send your secret key in the Authorization header, from your server or an MCP client on your own machine 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.
An MCP client on your own machine is the one exception to the desktop app rule: its config may hold the key the MCP server uses. Give it a key of its own, so you can roll or revoke it alone. Never put a key in an app you ship to others, a browser page or a repository.
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.