Simio API authentication: create and use your API key

Simio API requests are authenticated with a company API key sent in the simio-api-key header. Create it in Simio under Settings → Integrations & developers → Credentials.

Every request to the Simio API must include a valid API key. Each company has a single active API key, which grants access to your company’s data and should be kept secret: treat it like a password. A missing or invalid key returns a 401 Unauthorized response.

Create your API key

1. Log in to Simio

   Go to getsimio.app and sign in with an admin account. Only admins can create, rotate or revoke the API key.

2. Open the Credentials page

   Open Settings, then select Credentials in the Integrations & developers section.

3. Click Create API key

   Click Create API key. The new key works immediately.

4. Copy and store the key securely

   Copy the key right away: this is the only time it is shown. Store it in an environment variable or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your platform’s built-in secret store.

Once created, the Credentials page shows a masked version of the key, along with its creation date and the date it was last used.

Using your API key

Send your API key in the simio-api-key header of every request:

curl -X POST https://getsimio.app/api/campaigns/send \
  -H "simio-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 42, "contacts": ["[phone]"] }'

API keys have the format simio_<key_id>_<secret>. Always send the full value.

The key identifies your company: you do not need to send any company code or workspace identifier.

Never expose your API key in client-side code, public repositories, or frontend JavaScript. If a key is compromised, revoke it immediately from Settings → Integrations & developers → Credentials.

Key permissions

Your API key belongs to your company, not to a user. It grants access to every endpoint of the Simio API for your company. Your company must also have an active subscription: requests are rejected with 403 Forbidden otherwise.

The same key is used by the Simio integrations that call the API, such as the External API connector and the Easiware, Gorgias and Brevo webhooks. Remember to update them whenever the key changes.

Rotate or revoke your key

From the Credentials page, an admin can replace the key in two ways:

Action	When to use it	Effect on the current key
Rotate key	Planned key change	A new key replaces it right away. The current key keeps working for 24 hours, so you can update your integrations without downtime.
Revoke key	The key may have leaked	The key stops working immediately, with no grace period. Every integration using it fails until you create a new key.

If the key may have leaked, revoke it instead of rotating it: a rotated key stays usable for 24 more hours. Revoking cannot be undone.

Error responses

401 Unauthorized: missing or invalid API key

Returned when the simio-api-key header is absent, or when the key does not exist, has been revoked or has expired after a rotation.

{
  "detail": "Invalid API key"
}

Fix: Check that you are sending the header as simio-api-key: YOUR_API_KEY and that the full key was copied correctly from the Credentials page. If the key was rotated more than 24 hours ago, use the new key.

403 Forbidden: subscription required

Returned when the key is valid but your company does not have an active Simio subscription.

{
  "detail": "Subscription required"
}

Fix: Check your subscription in the Simio application, or contact Simio support.