Docs

Developers / API

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

  1. Open the create dialog

    On Settings > Developers > API keys, click Create Key.

  2. 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.

  3. 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.

  4. Create the key

    Click Create Key at the bottom of the dialog.

  5. 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.

  6. 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.

StatuscodeCause
401authentication_errorThe key is missing, mistyped or revoked.
403authorization_errorThe key doesn't have a scope that the endpoint needs. The message names the scopes that would allow it.
429rate_limit_exceededThe 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:

GroupPermissionScopeAllows
TicketsRead Ticketstickets:readView tickets and their details
TicketsWrite Ticketstickets:writeCreate and update tickets
TicketsDelete Ticketstickets:deleteDelete tickets
KnowledgeRead Knowledgeknowledge:readSearch the knowledge base
ToolsRead Toolstools:readView available automation tools
ToolsWrite Toolstools:writeCreate and manage automation tools
ToolsExecute Toolstools:executeExecute automation tools
RunbooksRead Runbooksrunbooks:readView runbooks and their configurations
RunbooksWrite Runbooksrunbooks:writeCreate and update runbooks and forms, and view drafts, revisions, templates, and the authoring guide
TriggersRead Triggerstriggers:readView triggers and their run history
TriggersWrite Triggerstriggers:writeCreate and manage triggers
Custom API SourcesRead Custom API Sourcescustom_api_sources:readView custom API sources and their tools
Custom API SourcesWrite Custom API Sourcescustom_api_sources:writeCreate and manage custom API sources
External MCP ServersRead External MCP Serversexternal_mcp_servers:readView external MCP server connections
External MCP ServersWrite External MCP Serversexternal_mcp_servers:writeCreate and manage external MCP servers
Users & DepartmentsRead Usersusers:readView user profiles and details
Users & DepartmentsRead Departmentsdepartments:readList departments and their members
Users & DepartmentsWrite Departmentsdepartments:writeCreate and update departments and their per-department configuration
CategoriesRead Categoriescategories:readView the ticket categories of departments
CategoriesWrite Categoriescategories:writeCreate and update the ticket categories of departments
Access RulesRead Access Rulesaccess_rules:readView access rules
Access RulesWrite Access Rulesaccess_rules:writeCreate and update access rules
SettingsRead Settingssettings:readView organization settings
SettingsWrite Settingssettings:writeUpdate organization settings
ArtifactsRead Artifactsartifacts:readView stored artifacts
ArtifactsWrite Artifactsartifacts:writeCreate and manage artifacts
AuditRead Audit Logaudit:readRead the audit log (e.g. to stream into a SIEM)
OtherRead Campaignscampaigns:readView campaigns, their recipients, and submitted responses
OtherRead Alertsalerts:readView alerts about problems with integrations and jobs
OtherRead Configurationconfig:readView Assistant settings and the automation opportunities report
OtherWrite Configurationconfig:writeUpdate Assistant settings
OtherRead Applicationsapplications:readView 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.

  1. Open the key's menu

    On Settings > Developers > API keys, click the ⋮ menu at the end of the key's row, then click Revoke Key.

  2. 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.

  • 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