API keys
Create scoped keys that let your scripts and services call the Risotto public API, and revoke a key when you no longer need it
An API key lets a script or service outside Risotto call the Risotto public API: for example, a Jira Automation rule that opens tickets, or a nightly job that copies tickets into a data warehouse. Each key has a set of scopes that limit what it can do, and it acts for your whole organization rather than for a person.
Go to Settings > Developers > API keys. Only Org Admins and Managers see this page.
The table lists your organization's active keys:
- Name, with the key's first 12 characters under it, so you can tell keys apart.
- Scopes - how many scopes the key has. Hover over the count to see their names.
- Last Used - when the key last authenticated a request, or Never.
- Created - when the key was created.
- Created By - the email address of the person who created the key. This column shows on wide screens only.
Risotto stores only a hash of each key. Nobody, including Risotto, can show you a key's full value after you close the dialog that creates it.
Create a key
Open the create dialog
On Settings > Developers > API keys, click Create Key.
Name the key
In Name, enter a name that says where the key is used, for example
Jira Automation. The name can be up to 100 characters.Choose permissions
Under Permissions, check the scopes the key needs, and nothing more. Read Tickets is checked when the dialog opens. A key needs at least one scope. See Scopes.
Create the key
Click Create Key at the bottom of the dialog.
Copy the key
The API Key Created dialog shows the full key, which starts with
rso_live_. Click the copy button next to it, and store the key in your secret manager or in the tool that will use it.Close the dialog
Click Done. The key appears in the table.
You can't edit a key after you create it. To change a key's name or scopes, create a new key with the settings you want, update the tool that uses the old key, and then revoke the old key. Keys don't expire. A key works until you revoke it.
Use a key
Send requests to the public API at:
https://api.tryrisotto.com/v1
Put the key in the Authorization header as a bearer token. Risotto also accepts the key in an X-API-Key header. For example, this request lists the five newest tickets, and needs a key with the Read Tickets scope:
curl "https://api.tryrisotto.com/v1/tickets?limit=5" \
-H "Authorization: Bearer rso_live_EXAMPLEKEYdoNotUse00000000000000"
The full list of endpoints, the scope each one needs, their parameters and their request bodies is in the API reference. The OpenAPI spec it's built from is at /docs/openapi.yaml. Signed-in users can also try requests in the dashboard: click Help at the bottom of the sidebar, then click API reference.
Every response carries an X-Request-ID header. A request made with a valid key also appears in the request log under the same request ID, so you can look up a call that failed.
Errors
Errors come back as JSON with an error object that holds a code and a message.
| Status | code | Cause |
|---|---|---|
401 | authentication_error | The key is missing, mistyped or revoked. |
403 | authorization_error | The key doesn't have a scope that the endpoint needs. The message names the scopes that would allow it. |
429 | rate_limit_exceeded | The key has used up its hourly request limit. The message says how many seconds to wait. |
Rate limits
Each key can make up to 1,000 requests to the public API per hour, unless Risotto has set a different limit for your organization. Each key has its own limit, so one busy key doesn't slow down another. Responses carry these headers:
X-RateLimit-Limit- the key's hourly limit.X-RateLimit-Remaining- how many requests the key has left in the current hour.X-RateLimit-Reset- a Unix timestamp for when the count resets.
Keys and the MCP server
People and AI assistants such as Claude Desktop, Claude Code, Cursor and Codex connect to the Risotto MCP server with OAuth, not with an API key. Risotto refuses an API key from these clients and tells them to sign in instead. A headless MCP client, such as a scheduled job that can't complete a sign-in, can send an API key as its bearer token. It sees only the MCP tools that the key's scopes allow.
Scopes
A scope allows one kind of access. The Permissions list in the create dialog groups the scopes like this:
| Group | Permission | Scope | Allows |
|---|---|---|---|
| Tickets | Read Tickets | tickets:read | View tickets and their details |
| Tickets | Write Tickets | tickets:write | Create and update tickets |
| Tickets | Delete Tickets | tickets:delete | Delete tickets |
| Knowledge | Read Knowledge | knowledge:read | Search the knowledge base |
| Tools | Read Tools | tools:read | View available automation tools |
| Tools | Write Tools | tools:write | Create and manage automation tools |
| Tools | Execute Tools | tools:execute | Execute automation tools |
| Runbooks | Read Runbooks | runbooks:read | View runbooks and their configurations |
| Runbooks | Write Runbooks | runbooks:write | Create and update runbooks and forms, and view drafts, revisions, templates, and the authoring guide |
| Triggers | Read Triggers | triggers:read | View triggers and their run history |
| Triggers | Write Triggers | triggers:write | Create and manage triggers |
| Custom API Sources | Read Custom API Sources | custom_api_sources:read | View custom API sources and their tools |
| Custom API Sources | Write Custom API Sources | custom_api_sources:write | Create and manage custom API sources |
| External MCP Servers | Read External MCP Servers | external_mcp_servers:read | View external MCP server connections |
| External MCP Servers | Write External MCP Servers | external_mcp_servers:write | Create and manage external MCP servers |
| Users & Departments | Read Users | users:read | View user profiles and details |
| Users & Departments | Read Departments | departments:read | List departments and their members |
| Users & Departments | Write Departments | departments:write | Create and update departments and their per-department configuration |
| Categories | Read Categories | categories:read | View the ticket categories of departments |
| Categories | Write Categories | categories:write | Create and update the ticket categories of departments |
| Access Rules | Read Access Rules | access_rules:read | View access rules |
| Access Rules | Write Access Rules | access_rules:write | Create and update access rules |
| Settings | Read Settings | settings:read | View organization settings |
| Settings | Write Settings | settings:write | Update organization settings |
| Artifacts | Read Artifacts | artifacts:read | View stored artifacts |
| Artifacts | Write Artifacts | artifacts:write | Create and manage artifacts |
| Audit | Read Audit Log | audit:read | Read the audit log (e.g. to stream into a SIEM) |
| Other | Read Campaigns | campaigns:read | View campaigns, their recipients, and submitted responses |
| Other | Read Alerts | alerts:read | View alerts about problems with integrations and jobs |
| Other | Read Configuration | config:read | View Assistant settings and the automation opportunities report |
| Other | Write Configuration | config:write | Update Assistant settings |
| Other | Read Applications | applications:read | View the applications that access can be requested for |
The same scopes gate the MCP server's tools. See Available scopes on the MCP server page for the tools each scope opens.
Revoke a key
Revoke a key when the tool that uses it is retired, when you replace the key, or when the key may have leaked.
On Settings > Developers > API keys, click the ⋮ menu at the end of the key's row, then click Revoke Key.
Confirm
In the Revoke API Key? dialog, click Revoke Key.
The key stops working immediately: every request that uses it fails with 401. The key leaves the table, and you can't restore it.
Related
- Request log - every request your keys make, with its status and errors.
- Webhooks - have Risotto call your systems when something happens, instead of polling the API.
- MCP server - connect AI assistants to Risotto.
Something wrong or missing? Report an issue · View as Markdown