> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# API Keys

> Create, secure, and manage API keys for Persona sandbox and production environments.

To access the Persona API, you'll need an API key. Each environment has its own API key; select the API key for the specific environment you would like to use.

## Getting an API Key

### Sandbox

[Sign up](https://withpersona.com/dashboard/signup) to get immediate access to a sandbox API key and start evaluating the API with sample data.

### Production

When you're ready to use the API in production using live data, please [contact us](https://app.withpersona.com/dashboard/contact-us).

### Already have an account?

If you already have an account in the Dashboard, you can [find your API keys in the API Keys Section](https://app.withpersona.com/dashboard/api-keys).

### Dashboard RBAC prerequisites

To view, create, or modify API keys in the Persona Dashboard, your user account must have the built-in **Admin** role, or a custom role with API Key permissions enabled for the current environment.

If the **Generate Key** or **Create API Key** button is disabled or grayed out in your Dashboard:

* Your user role lacks API Key administration privileges.
* Contact an Admin to either generate the required key or elevate your user role under **Admin > Team Members**.

> **Info**
>
> **Dashboard Roles vs. API Key Scopes:** Dashboard RBAC roles control what human operators can see and perform in the web interface. API key scopes (documented below) govern the actions that programmatic HTTP requests using your secret token are permitted to execute.

> **Warning**
>
> Your API keys carry many privileges, so be sure to keep them secure! Do not
> share your secret API keys in publicly accessible areas such as GitHub,
> client-side code, and so forth.

### Testing the API

You can test the API resources directly in this reference by providing your production or sandbox API key.

If you click on "Documentation" in the dashboard, the API examples will pre-fill with your sandbox key.

![api-keys-dashboard](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/api-keys-dashboard.png)

## Permissions

Each API key can be configured with specific permissions in order to limit read or write access to specific API resources. This list can change at any time and should not be considered to be exhaustive. You can configure permissions for your API key in the Dashboard by going to [API > API Keys > Edit > Permissions](https://app.withpersona.com/dashboard/api-keys).

| Permission                  | Description                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `account.read`              | Read [Accounts](/api-reference/accounts)                                                |
| `account.write`             | Create/Update [Accounts](/api-reference/accounts)                                       |
| `account_type.read`         | Read [Account Types](/api-reference/account-types)                                      |
| `api_log.read`              | Read [API Logs](/api-reference/api-logs)                                                |
| `api_key.write`             | Create/Update [API Keys](/api-reference/api-keys) (Disabled by default)                 |
| `api_key.read`              | Read [API Keys](/api-reference/api-keys) (Disabled by default)                          |
| `api_key.scim`              | Use for SCIM Integrations (Disabled by default)                                         |
| `case.read`                 | Read [Cases](/api-reference/cases)                                                      |
| `case.write`                | Create/Update [Cases](/api-reference/cases)                                             |
| `case_template.read`        | Read [Case Templates](/api-reference/case-templates)                                    |
| `client_token.read`         | Read Client Tokens                                                                      |
| `client_token.write`        | Create/Update Client Tokens                                                             |
| `connect.read`              | Read [Connections and Share Tokens](/api-reference/connect)                             |
| `connect.write`             | Create/Update [Connections and Share Tokens](/api-reference/connect)                    |
| `connect_connection.read`   | Read [Connections](/api-reference/connect)                                              |
| `connect_connection.write`  | Create/Update [Connections](/api-reference/connect)                                     |
| `connect_share_token.read`  | Read [Share Tokens](/api-reference/connect)                                             |
| `connect_share_token.write` | Create/Update [Share Tokens](/api-reference/connect)                                    |
| `document.read`             | Read [Documents](/api-reference/documents)                                              |
| `document.write`            | Create/Update [Documents](/api-reference/documents)                                     |
| `event.read`                | Read [Events](/api-reference/events)                                                    |
| `filing.write`              | Create/Update Filings                                                                   |
| `graph.read`                | Read [Graph](/api-reference/graph)                                                      |
| `graph.write`               | Create/Update [Graph](/api-reference/graph)                                             |
| `importer.read`             | Read [Importers](/api-reference/importers)                                              |
| `importer.write`            | Create/Update [Importers](/api-reference/importers)                                     |
| `inquiry.read`              | Read [Inquiries](/api-reference/inquiries)                                              |
| `inquiry.write`             | Create [Inquiries](/api-reference/inquiries)                                            |
| `inquiry_template.read`     | Read [Inquiry Templates](/api-reference/inquiry-templates)                              |
| `inquiry_template.write`    | Create/Update [Inquiry Templates](/api-reference/inquiry-templates)                     |
| `list.read`                 | Read [Lists](/api-reference/lists)                                                      |
| `list.write`                | Create/Update [Lists](/api-reference/lists)                                             |
| `mcp.access`                | Use Persona's Machine Learning Classification Platform (MCP)                            |
| `privacy_pass.write`        | Create [Privacy Passes](/api-reference/relay/create-a-privacy-pass) for [Relay](/relay) |
| `report.read`               | Read [Reports](/api-reference/reports)                                                  |
| `report.write`              | Create/Update [Reports](/api-reference/reports)                                         |
| `session.read`              | Read Sessions                                                                           |
| `session.write`             | Create/Update Sessions                                                                  |
| `txn.read`                  | Read [Transactions](/api-reference/transactions)                                        |
| `txn.write`                 | Create/Update [Transactions](/api-reference/transactions)                               |
| `theme_set.read`            | Read [Theme Sets](/api-reference/theme-sets)                                            |
| `theme_set.write`           | Create/Update [Theme Sets](/api-reference/theme-sets)                                   |
| `user_audit_log.read`       | Read [User Audit Logs](/api-reference/user-audit-logs)                                  |
| `verification.read`         | Read [Verifications](/api-reference/verifications)                                      |
| `verification.write`        | Create/Update [Verifications](/api-reference/verifications)                             |
| `webhook.read`              | Read [Webhooks](/api-reference/webhooks)                                                |
| `webhook.write`             | Create/Update [Webhooks](/api-reference/webhooks)                                       |
| `workflow.read`             | Read [Workflows](/api-reference/workflows)                                              |
| `workflow.trigger`          | Trigger [Workflows](/api-reference/workflows)                                           |

## Scoping and Least Privilege

To minimize security exposure, follow the principle of least privilege when generating API keys:

* **Restrict scopes:** Only grant the permissions strictly necessary for your backend service. For example, a service that only generates inquiry links needs `inquiry.write` and does not need `account.write` or `report.write`.
* **Restrict visible records with Payload Filters:** `inquiry.read` and `inquiry.write` are environment-wide permissions and cannot be scoped to specific Inquiry Templates. If you need to limit which records a key can return, Enterprise customers can configure [Payload Filters](/api-reference/api-key-payload-filters), which match each record's serialized response against a filter. Note that payload filters are a response-visibility control, not a write-authorization boundary: non-matching records are omitted from list responses (rather than returning a `403`), single-resource reads of a non-matching record return `403 Forbidden`, and filters do not prevent creating records under another template.

## Key Rotation Best Practices

To rotate an active API key without incurring production downtime:

1. **Generate a replacement key:** In the Persona Dashboard under **API > API Keys**, create a new API key with the identical permissions (and payload filter, if any) required by your service.
2. **Deploy the new key:** Update your application's environment configuration or secret manager with the new API key and deploy the update.
3. **Verify requests in API Logs:** Inspect your incoming traffic under **API > API Logs** to ensure requests from your service are succeeding with the new key token.
4. **Expire the old key:** Once all traffic has migrated to the new key, return to the Dashboard and expire the retired API key.

## Troubleshooting Common Errors

### `401 Unauthorized`

A `401 Unauthorized` error indicates Persona could not authenticate the request.

Common causes:

* **Missing or malformed Authorization header:** Ensure your HTTP request includes the header `Authorization: Bearer <your_api_key>`.
* **Environment mismatch:** Sandbox API keys (`persona_sandbox_...`) cannot be used against the Production environment, and Production keys (`persona_production_...`) cannot be used in Sandbox. Ensure the key prefix matches your target environment.
* **Deactivated or deleted key:** The key used in the request may have been revoked or deleted in the Dashboard.

### `403 Forbidden` (`insufficient_permissions`)

A `403 Forbidden` error indicates the API key was authenticated, but lacks permission to perform the requested operation.

Common causes:

* **Missing required scope:** Review the endpoint's required permission in this reference (e.g. `inquiry.write` for `POST /api/v1/inquiries`) and verify that your API key carries that permission under **API > API Keys**.
* **Template or resource restriction:** If the API key is restricted to specific Inquiry Templates, attempting to create or fetch an inquiry under a different template ID triggers `insufficient_permissions`.
* **Disabled administrative scopes:** Scopes such as `api_key.write` and `api_key.scim` are restricted by default and cannot be assigned without administrative enablement.