API keys

An API key authenticates a service to one workspace. Its scopes say which operations it may perform; project IDs restrict where it may perform them. Named read grants and workspace-resource access are additional controls.

You need a Semogram account as owner/admin to create keys in the UI, or an existing unrestricted org:manage key to administer them through the public API. The raw secret is returned only at creation; later listings expose identity/prefix and permissions, not a recoverable secret.

Example: Maintenance query reader

Assume the workspace has a Maintenance project, a published equipment query and a binding requiring maintenance:read. The service only needs to discover and execute that query; it does not administer endpoints or plugins.

Prepare a least-access service key for the Maintenance project's published equipment query. It needs project discovery, query reads/execution and the binding grant maintenance:read. Do not grant writes, organization management or shared workspace resources. Explain the exact project ID and scopes for my review; do not request or display the raw secret in chat.

curl --request POST "https://platform.semogram.com/api/v1/api-keys" \
  --header "Authorization: Bearer ${SEMOGRAM_ADMIN_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"name":"Maintenance query reader","scopes":["projects:read","queries:read","queries:execute"],"readPermissions":["maintenance:read"],"projectIds":["<MAINTENANCE_PROJECT_UUID>"],"workspaceResources":false,"expiresAt":"2027-01-01T00:00:00Z"}'

Project restrictions

An empty projectIds list means all current and future projects, not no projects. A nonempty list is an allowlist; new projects are excluded. Every selected ID must belong to the key's workspace.

A restricted key needs workspaceResources true to use shared data endpoints/plugins and the relevant operation scopes. That flag is workspace-wide shared-resource access, not permission to just one selected endpoint. An unrestricted key already has workspace-resource reach subject to scopes.

org:manage cannot be combined with a project restriction. It is broad administration and can stand in for operation scopes on unrestricted keys. Prefer a separate administrator credential from a query-reading service.

Verify the key

Use it to list the allowed project and run a bounded published query with its expected subject. Inspect the real response/completeness and test an out-of-allowlist project is denied. Do not infer correct access from creation alone.

GET /api/v1/api-keys lists nonrevoked keys for an org:manage caller. Inspect key ID, prefix, scopes, read grants, project IDs, workspaceResources, expiry and last use.

Update, rotate and revoke

The key permissions UI and PATCH /api/v1/api-keys/<KEY_UUID> can change projectIds, workspaceResources and readPermissions. They do not edit scopes, name or expiry. Create a new key when those need to change.

For rotation, create the replacement with reviewed permissions, update the service's protected configuration, verify its requests, then revoke the old key. In the UI use Revoke key and confirm the exact key. DELETE /api/v1/api-keys/<KEY_UUID> revokes it through the public API. Revocation is irreversible; issue another credential if needed.

Expiry/revocation prevents new authentication. It does not undo earlier writes or erase run history. Operations that require an accountable current member can also fail after the creator loses membership. Read the action's requirements rather than assuming a key replaces every human approval.

Operation scopes

Choose individual scopes for the service's actual actions. The UI groups them with human-readable labels; the following are their serialized names.

Use the specific action's contract to select its required scope. For example, publishing a query and executing it are different actions. This table lists scopes accepted by API-key creation; not every internal/OAuth permission is a selectable key scope, and a scope name does not guarantee a corresponding public endpoint exists.