> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alcmeon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Log in to Simio">
    Go to [getsimio.app](https://getsimio.app) and sign in with an **admin** account. Only admins can create, rotate or revoke the API key.
  </Step>

  <Step title="Open the Credentials page">
    Open **Settings**, then select **Credentials** in the **Integrations & developers** section.
  </Step>

  <Step title="Click Create API key">
    Click **Create API key**. The new key works immediately.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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:

```bash theme={null}
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": ["+33612345678"] }'
```

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.

<Warning>
  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**.
</Warning>

## 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. |

<Info>
  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.
</Info>

## Error responses

<Accordion title="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.

  ```json theme={null}
  {
    "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.
</Accordion>

<Accordion title="403 Forbidden: subscription required">
  Returned when the key is valid but your company does not have an active Simio subscription.

  ```json theme={null}
  {
    "detail": "Subscription required"
  }
  ```

  **Fix:** Check your subscription in the Simio application, or contact Simio support.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.