API
API keys let your own tools query Alma’s knowledge base. Each key reads only what you scope it to.
Creating a key
Click New API key.
Key name — for your own reference. A blank name becomes Untitled key.
Reads as — either Read as admin (no filter — everything the organization knows), or bound to one or more people and groups. Binding filters everything the key reads to the union of what those subjects could see — useful when a key powers something a subset of people uses.
A bound key fails closed. If any person or group it reads as is deleted, the key returns 403 rather than widening to org-wide access.
Scopes — at least one is required:
| Scope | Grants |
|---|---|
| Knowledge & search | Search the knowledge base |
| Memory | Read memories |
| People | Read the directory |
| Groups | Read groups |
| Outcomes | Read outcomes |
| Goals & initiatives | Read goals |
Knowledge and Memory are on by default.
Keys created in the Console are read-only. All six scopes above are reads — there’s no way to create a writing key from the Console.
Store the secret immediately
The key is shown once, at creation:
Later views show only alma_sk_live…b4e2 — enough to identify the key, not
enough to use it. If you lose a secret, revoke the key and create a new one.
Using a key
curl
curl https://api.alma.team/v1/topics \
-H "Authorization: Bearer $ALMA_API_KEY"Common endpoints:
/v1/topics— topics in Memory/v1/topics/{id}/updates— a topic’s narrative/v1/topics/{id}/summary— a topic, summarized
Full reference: API → Docs in the Console, rendered from the OpenAPI spec.
Revoking a key
Click the trash icon to revoke.
Revoke is immediate with no confirmation. It’s a soft revoke — the row stays for the audit trail, marked Revoked, but the key stops working instantly and can’t be reinstated.
Limits
Coming soon. Keys created in the Console never expire, can’t be edited after creation (revoke and recreate to change scopes), and can’t be granted write or execute scopes or source bindings. Email help@alma.team if you need any of these.