Permissions

At a glance

Each API key has scopes that define the authorized operations. Assign only the permissions needed for each key to follow the principle of least privilege.

Technical prerequisites

• An API key created (see API Keys)
• Access to workspace settings

Available scopes

Scopes provide fine-grained control over what an API key can do within your workspace.

Scope	Access	Description
read:nodes	Read	List and view ontology entities.
write:nodes	Write	Create, update, and delete entities.
read:edges	Read	List and view relationships.
write:edges	Write	Create, update, and delete relationships.
read:livedata	Read	View Live Data sources and data.
write:livedata	Write	Configure and manage Live Data sources.
read:events	Read	View the event history.
admin	Full	Full workspace access (includes all scopes).

Scope inheritance

Scopes follow an inheritance logic:

• A write:* scope automatically includes the corresponding read:* scope. For example, write:nodes also allows reading entities.
• The admin scope includes all other scopes. A key with admin has full access to the workspace.

You do not need to add read:nodes if you already assign write:nodes.

Quota management

Each plan defines request limits per API key.

Plan	Requests/min	Requests/day
Starter	60	10,000
Pro	300	100,000
Enterprise	Custom	Custom

When a key exceeds its quota, subsequent requests receive a 429 Too Many Requests response until the next reset cycle.

Rotation and revocation

Regular key rotation strengthens the security of your integrations.

• Recommended rotation: every 90 days.
• Grace period: after rotation, the old key remains valid for 24 hours. This gives you time to update your integrations.
• Immediate revocation: if a key is compromised, revoke it immediately. Access is cut off instantly, with no grace period.

Usage monitoring

Monitor each API key's usage to detect anomalies and optimize your quotas.

The usage dashboard shows for each key:

• Total request count for the selected period
• Success rate (percentage of 2xx responses)
• Most requested endpoints to identify active integrations

Principle of least privilege
Never use the admin scope for integrations that only need read access. Assign only the scopes strictly necessary for each key.

Limits

Limit	Value
Keys per workspace	50
Scopes per key	10 maximum
Grace period after rotation	24 hours

Troubleshooting

Problem	Cause	Solution
403 Forbidden	Insufficient scope	Add the required scope to the key from the settings.
429 Too Many Requests	Rate limit exceeded	Wait for the counter to reset or upgrade to a higher plan.
Key not recognized	Key revoked or expired	Create a new key and update your integration.
Partial access	Missing write scope	Verify the key has the necessary write scope.

Need help?

See the API Keys page to create or manage your keys, or write to us: Support and contact.