Developers
Security best practices
How to hold credentials, verify webhooks, limit blast radius and connect AI assistants safely.
Credentials
- Keep keys and secrets in a secret manager or environment variables, never in source control, front-end code, mobile apps or chat. Keys start with
spk_, access tokens withspo_and webhook secrets withwhsec_so secret scanners can find a leaked one. - Give every integration its own key so you can see its usage and revoke it alone.
- Set the shortest expiry that works and turn on Require keys to expire for the organization. Rotate before expiry with Replace: the overlap lets you deploy without downtime.
- Restrict a key to the networks it runs from (Allowed networks). A stolen key then fails from anywhere else.
- Prefer OAuth where a person is involved: tokens expire in an hour, act as the person, and are revoked with one click.
- Send credentials only in the
Authorizationheader over HTTPS, never in a URL. Don’t log request headers.
Least privilege
- Grant only the scopes the integration uses. Write scopes (
interactions:write) deserve their own key. - Use a lower Calls per minute on keys that should never run hot, so a bug or a leak can’t exhaust your allowance.
- Watch API usage for a key that suddenly makes many calls, errors or throttled calls. The key list shows when and from where each key was last used.
- Treat
403 IP_NOT_ALLOWEDand repeated401from a key you own as an alert.
Webhooks
- Verify
TINIUN-Signatureon the raw body, in constant time, and reject timestamps older than 5 minutes (see verifying). - Make handlers idempotent: delivery is at least once. De-duplicate on the event
id. - Answer quickly with
2xxand do the work afterwards. Use HTTPS with a valid certificate; TINIUN refuses private and local addresses and doesn’t follow redirects. - Rotate the secret on a schedule and whenever someone with access leaves. Use the overlap so nothing is dropped.
AI assistants
- Connect assistants with OAuth so each person’s own access applies. Don’t share one broad API key with a whole team of people who couldn’t otherwise see that data.
- Remember the assistant’s provider receives what the tools return. Check your agreement covers employee data.
- Tool results are data, not instructions: don’t let an assistant take actions on other systems because text in a result told it to.
- Review connected assistants under Settings → Integrations → OAuth applications and remove ones you no longer use. Every MCP tool call is in the audit log.
If a secret leaks
- Revoke the key (Revoke) or delete the OAuth authorization. This takes effect immediately.
- Look at API usage and the audit log for calls you don’t recognize, and at
lastUsedIpon the key. - Create a replacement with the narrowest scopes and an allowed network, and deploy it.
- For a webhook secret, choose New secret with no overlap and replay missed deliveries.
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
