API Keys
API keys let approved integrations access sayhii programmatically. 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
- (Optionally) hide revoked keys from the list
Each key entry shows: key ID (not the secret), status, scopes, optional expiration, created date, last used (if available), and notes you added when issuing the key.
Key Statuses
| Status | Meaning |
|---|---|
| active | Key can be used for requests |
| rotating | A replacement key was issued; old key still valid until you finalize revocation (if you chose not to revoke immediately) |
| 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 so you can update dependent services. Once everything is using the new key and the old key shows no recent usage, finalize by revoking it.
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., “Payroll sync”).
- Create and copy the key value immediately.
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 |
|---|---|
user:read | Read user data |
user:write | Create or update user data |
dictionary:read | Read dictionaries |
dictionary:write | Modify dictionaries |
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 waiting for you to finish migrating clients before you revoke it.
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.