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

*Product example: Settings, Developers, API keys: the API Keys description, three keys with their scopes and dates, and Create Key in outline.*

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](#scopes).

   *Product example: The Create API Key dialog: the name Jira Automation, and the Tickets permissions with Read Tickets checked and Write Tickets in outline.*

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.

   *Product example: The API Key Created dialog: the new key in full, shown once, with its copy button in outline.*

6. **Close the dialog**

   Click **Done**. The key appears in the table.

> **Warning:** The key is shown only once. If you lose it, revoke it and create a new one.

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](#revoke-a-key) the old key. Keys don't expire. A key works until you revoke it.

## Use a key

Send requests to the public API at:

```text
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:

```bash
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](https://www.tryrisotto.com/docs/api-reference). The OpenAPI spec it's built from is at [/docs/openapi.yaml](https://www.tryrisotto.com/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](https://www.tryrisotto.com/docs/dashboard/settings/developers/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](https://www.tryrisotto.com/docs/integrations/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](https://www.tryrisotto.com/docs/integrations/mcp-server#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**.

   *Product example: The SIEM audit export key's menu open on the API keys page, with Revoke Key in outline.*

2. **Confirm**

   In the **Revoke API Key?** dialog, click **Revoke Key**.

   *Product example: The Revoke API Key? dialog for SIEM audit export, with Revoke Key in outline.*

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](https://www.tryrisotto.com/docs/dashboard/settings/developers/request-log) - every request your keys make, with its status and errors.
- [Webhooks](https://www.tryrisotto.com/docs/integrations/webhooks) - have Risotto call your systems when something happens, instead of polling the API.
- [MCP server](https://www.tryrisotto.com/docs/integrations/mcp-server) - connect AI assistants to Risotto.

Source: https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys
