Help Guides
API keys
API keys let servers call Substratal without a person signing in. They never belong in an app or a browser. The Hub apps themselves never hold one: you manage keys with your own signed-in session.
Create a key
In Create API key choose:
- Scope.
platform(needsapi_keys.manage), or one Application. An app key can only ever reach its own Application. - Permissions. Only what this integration needs.
- Mode. Test keys see and create only test data, which is purged after 30 days. Live keys see only live data.
- Intended use. AI agent keys can't run destructive operations unless you explicitly allow it, and that choice is audited.
- Expiry. Optional. A year is a good default.
Store the secret
The secret (satk_live_…) is shown once, on Secret reveal. Copy it into your secret manager before closing. On iPhone and iPad the copy expires from the clipboard after 60 seconds and never syncs to your other devices. The secret is hidden while the screen is being recorded or mirrored.
Lost it? You can't see it again. Rotate the key or create a new one.
Rotate without downtime
Rotate issues a new secret and kills the old one immediately. For zero downtime, do this instead (see the tutorial):
- Create a second key with the same scope and permissions.
- Deploy it to your service.
- Watch the old key's Last used stop moving.
- Revoke the old key.
Revoke
Revoking is immediate and permanent. Anything still using the key gets 401. Data the key created is untouched.
Screens in this guide
KEY-01 · API keys KEY-02 · Create API key KEY-03 · Secret reveal KEY-04 · API key detail