API authentication

How to authenticate against the SIMCOAI API and keep your keys safe.

Keys

Authenticating a request

Send your API key in the X-SIMCOAI-API-Key header on every request. Keys are issued and revoked from the dashboard.

curl -sS https://api.simcoai.co.uk/calling/live-calls \
  -H "X-SIMCOAI-API-Key: $SIMCOAI_API_KEY" \
  -H "Content-Type: application/json"

Idempotency

Safe retries

Any request that creates something accepts an idempotency key. Send the same key on a retry and the original result is returned rather than a duplicate being created.

curl -sS -X POST https://api.simcoai.co.uk/calling/live-calls/CAxxxx/commands \
  -H "X-SIMCOAI-API-Key: $SIMCOAI_API_KEY" \
  -H "X-SIMCOAI-Idempotency-Key: refund-8815-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"command":"escalate"}'

Handling keys

Keeping keys safe

Treat an API key like a password. These rules are not optional.

Server side only

Never put a SIMCOAI API key in browser JavaScript, a mobile app bundle or a public repository.

Rotate on exposure

If a key may have leaked, revoke it in the dashboard and issue a new one. Revocation takes effect immediately.

One key per integration

Separate keys per system mean you can revoke one without breaking the others.