API access
Letting your own systems call the platform, using service accounts and API keys.
Service accounts
A service account is an account for software rather than a person. Use one whenever another system needs to talk to the platform: a website, a back-office application, a scheduled job.
Service accounts live under User management → Service accounts. They are covered in full on Service accounts, including how to create one, how it gets its rights, and how to manage its keys.
The essentials:
Identity
An automatically generated address. You choose the name and description.
Rights
From user group membership, exactly like a person. Add the account to groups.
Credentials
One or more API keys.
Status
Active or inactive. Deactivating blocks authentication without deleting anything.
Triggers, runs and their requests for approval, budgets and notification channels can also be managed through the API, so assistants that work on their own can be set up and followed from your own systems. Your account manager can tell you what access to the API involves for your organisation.
API keys
Create keys from the service account's Keys tab.
API Key name
Labels the key, so you know which system holds it.
Expiry date
Optional, up to one year ahead.
Working with keys sensibly
One key per consuming system. When something needs revoking, you revoke only that one.
Name keys after the system that holds them, not after the date you made them.
Set an expiry. A key that expires is a key that gets reviewed.
Rotate without downtime: create the new key, deploy it, confirm the system works, then delete the old one.
Deactivate before deleting when investigating. Deactivating the service account blocks access immediately and is reversible; deleting is not.
API documentation
The View API Documentation button on the service accounts screen opens the reference for the API key service, rendered from its own specification so it is always current.
The same page carries an ID Helper, which is more useful than it sounds. Most API calls need the identifier of an assistant, a session or a tool, and finding those by hand is tedious. The helper has two tabs:
Assistants: search your assistants, copy an assistant's ID, expand one to find session IDs.
Toolbox: search elements, copy a tool's ID, and inspect its arguments, including which are required and what their defaults are.
Click any ID to copy it.
Before you build against the API
Create a dedicated service account for the integration, not a shared one.
Give it only the groups it needs. It inherits everything those groups grant.
Create one key, note where it will be stored, and set an expiry.
Store the key in your own secret management, never in source code.
Record what it is for, so the next person understands why it exists.
Last updated
Was this helpful?