Authentication
Every request carries an API key. A key belongs to one workspace, its scopes say what it may do, and it can never do more than the member who created it.
Send your API key as a bearer token in the Authorization header of every request:
curl https://api-prod.lodol.com/api/v1/workflows \
-H "Authorization: Bearer $LODOL_API_KEY"A request without a valid key gets 401 Unauthorized.
Create a key
Create and revoke keys in Lodol under Settings › API Keys. Only the workspace's owners and admins can.
- A key belongs to one workspace. Every request it makes works with that workspace's workflows and runs, and its runs count toward that workspace's plan.
- You see the full key once, when you create it. Lodol keeps only its first characters and a hash, so a lost key can't be recovered: revoke it and create another.
- Keys look like
sk_live_followed by a random string with 256 bits of entropy. - Keys can expire. Set an expiry when you create a key, and create a new one before it lapses.
The number of keys a workspace can have depends on its plan:
| Plan | API keys |
|---|---|
| Free | 1 |
| Builder | 10 |
| Pro | 40 |
| Enterprise | Custom |
Scopes
Each key has one or more scopes, which decide the endpoints it can call:
| Scope | Allows |
|---|---|
workflows:read | Listing workflows and reading a workflow |
workflows:execute | Starting runs and stopping them |
executions:read | Listing runs and reading a run |
workflows:delete | Deleting workflows. Not included unless you tick Delete workflows when you create the key. |
executions:delete | Deleting runs. Not included unless you tick Delete runs when you create the key. |
Scopes add up: a key with workflows:read and workflows:execute can list and run workflows, but can't read runs without executions:read. Give each key only the scopes its job needs.
A key acts for the member who created it
A request has to be allowed by both the key's scopes and the role of the member who created the key:
- Running or stopping a workflow also needs the creator's role to include Run workflows.
- Deleting a workflow also needs the creator's role to include Delete workflows.
- Deleting a run also needs the creator's role to include Delete runs.
If the creator's role loses a permission, their keys lose it too. If the creator leaves the workspace, their keys stop working on every endpoint, so create replacement keys before someone leaves.
Keep keys safe
- Never put a key in code that runs in a browser or a mobile app, or commit it to a repository.
- Keep keys in environment variables or a secrets manager.
- Use one key per integration, with the fewest scopes it needs, so you can revoke one without breaking the others.
- Revoke keys you no longer use.
Quickstart
Create an API key, start a workflow run from your code, and read its result. About five minutes.
Errors and retries
The error codes the API returns and what to do about each, the request ID to quote to support, which requests are safe to retry, and how idempotency keys stop a retry from starting a run twice.