API Keys
This page covers admin-only tools in the sayhii portal. It's visible to organization admins, not to regular team members.
API Keys aren't self-serve yet. Contact your sayhii account team (support@sayhii.io) to have this enabled for your organization—there's nothing to set up until then.
API keys let your own systems access the sayhii Organization API programmatically to push roster and department updates. Keep them narrow in scope, rotate them regularly, and revoke them immediately if you suspect exposure.
The full key value is shown only once—right after you create or rotate it. If you lose it, create or rotate again. Never email or paste the secret in unsecured chats.
What You Can Do Here
From the API Keys page you can:
- Create a new key with selected scopes
- See existing keys and their status (active, rotating, revoked)
- Rotate a key to get a new secret
- Revoke a key you no longer need
Each key entry shows: key ID (not the secret), status, scopes, rate class, optional expiration, created date, last used (if available), and any notes you added when issuing the key.
Push Sources
A key isn't tied to a single system—it can act as any of your organization's declared push sources it has scope for, chosen per-call via a request header (see the Organization API's Push Sources section for the integration-facing details). Manage your declared push sources from the Integrations page before issuing keys for a new integration.
Key Statuses
| Status | Meaning |
|---|---|
| active | Key can be used for requests |
| rotating | A replacement key was issued; the old key still works for a limited grace window so you can update dependent services |
| revoked | Key is permanently disabled |
Rotation
Rotate when you need to change scopes, replace a lost secret, or follow your security schedule. If you don't select immediate revoke, the old key remains valid briefly (a short grace window) so you can update dependent services. Once everything is using the new key, finalize by revoking the old one—after the grace window elapses it stops working automatically either way.
Revocation
Revoke a key as soon as it is no longer required or if you believe it may be compromised. Revocation can’t be undone.
Creating a Key
- Click New Key.
- Select only the scopes the integration needs.
- (Optional) Set an expiration date.
- (Optional) Add a note describing the use case (e.g., “Nightly HRIS sync”).
- Create and copy the key value immediately.
Every self-service key is issued at the standard rate class (60 requests/minute). If an integration needs the burst class (300 requests/minute), contact your sayhii account team.
If you lose the secret, you’ll need to rotate or issue a new key—there is no way to view it again.
Scopes
| Scope | Purpose |
|---|---|
roster:write | Push (create/update) employee records via POST /v1/roster/sync |
roster:read | Read employee records already pushed—view only, cannot push data |
department:write | Push (create/update) department structure via POST /v1/departments/sync |
department:read | Read department structure already pushed—view only, cannot push data |
Read and write scopes are independent—holding roster:write doesn't grant
roster:read, and vice versa. Grant only what the integration actually needs (principle
of least privilege); prefer multiple small keys over one broad key.
Expiration
Setting an expiration helps enforce rotation. When a key expires it behaves like a revoked key. Choose shorter periods for write-enabled or sensitive automations; longer periods for stable read-only tasks that are monitored.
Recommended Rotation
- Write-enabled keys: every 60–90 days
- Read-only keys: every 90–180 days
- Immediate rotation or revocation if you see unexpected usage or a potential leak
When to Revoke
Revoke when:
- The integration is decommissioned
- Scopes are no longer required
- The key was exposed (committed, pasted, shared inadvertently)
If availability matters, rotate first (without immediate revoke), update clients, then revoke the old key.
FAQ
Can I view a secret later? No—issue or rotate to obtain a new secret.
What if I picked the wrong scopes? Rotate the key with the corrected scope set (or create a new one, then revoke the old).
Why can I still see a “rotating” key? It’s within its grace window, so it still works while you finish migrating clients—once that window passes it stops working automatically, or you can revoke it outright.
Do notes affect access? No, they’re just labels to help you track usage.
Best Practices Checklist
- Minimal scopes only
- Separate key per integration
- Rotation schedule documented
- Secrets stored in a secure secrets manager
- Monitor usage / last used
- Revoke immediately on exposure
Support
Need help with an integration or scope choice? Contact support@sayhii.io.