Authentication and scopes
Authenticate a service and constrain its workspace, projects and reads
Create a workspace API key using a Semogram account with administrative access, or an existing workspace-wide org:manage key. Store the secret when it is returned; later key listings do not recover it.
Send Authorization: Bearer YOUR_API_KEY on consumer requests. Use HTTPS and your service's secret store. Do not put the key in a URL or share it in an assistant prompt. Public pricing is unauthenticated; the Stripe webhook uses Stripe signature verification instead of this credential.
Authorization layers
| Layer | Meaning |
|---|---|
| Workspace | A key belongs to one workspace |
| Scope | Allows an operation family, such as pipelines:execute |
| Project allowlist | Restricts project-scoped resources |
| Workspace resource access | Explicit access to shared workspace resources for restricted keys |
| Named read grants | Satisfies permissions required by ontology bindings |
| Accountable actor and policy | Additional requirements for authoring, execution and governed changes |
A scope does not install a connector, grant database access or approve a write. A project allowlist does not automatically grant all workspace endpoints. org:manage is administrative access and cannot be project-restricted; use narrower keys for consumers.
Select scopes by task
| Task | Scopes |
|---|---|
| Discover workspace/project | org:read, projects:read |
| Execute and inspect pipeline | pipelines:execute, runs:read; add pipelines:read to inspect configuration |
| Read endpoint records | data:read, with workspace resource access |
| Execute published query | queries:execute, plus any required named binding grants |
| Manage queries/releases | queries:read, queries:write, queries:publish as appropriate |
| Inspect ontology/bindings | ontologies:read, bindings:read |
| Administer workspace | Workspace-wide org:manage |
The route catalog records the gate used by each route. Some operations also require current member permissions. Revocation, expiry or loss of the accountable actor can invalidate a previously working integration.
Verify a key
curl --fail-with-body -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
'https://platform.semogram.com/api/v1/organization'This requires org:read and returns { "organization": ... }. If the consumer key intentionally lacks this scope, verify its intended resource action instead. See API key administration for the platform setup and rotation flow.