> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prophia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys for the REST API and MCP server

The Prophia REST API authenticates with **API keys**. The MCP server accepts the same keys, or — recommended for MCP — [OAuth through your organization's identity provider](https://docs.prophia.com/developers/mcp/oauth-setup.md).

## Key types

| | Account API key | User API key |
| - | - | - |
| Scope | One account, not tied to any user — the REST API and MCP permissions chosen when it was created | One user in one account — that user's permissions, or fewer |
| Best for | Server-to-server integrations | Per-person tooling, least-privilege access |
| Issued via | **Self-serve** — an admin creates it in the web app | **Self-serve** — an admin creates it for any user in the web app |

Both are created on the **API/MCP Config** tab in **Account Settings**, under **Authorization Options**. The tab appears for account admins on accounts with the REST API module enabled. On accounts with granular permissions, it also appears for users with REST API or MCP access, who can manage their own user keys there.

> [!NOTE]
>
> On accounts without granular permissions, an account key has full read and write access to the account's data, and a user key has exactly its user's access. The web app doesn't show permission choices on those accounts.

### Creating an account key

**1. Select Account Tokens**

On the **Authorization Options** card, choose the **Account Tokens** segment, then **Create New Account Token**.

**2. Choose its permissions**

Every REST API and MCP permission starts selected. Untick anything the key shouldn't be able to do. An account key isn't tied to a user, so these permissions are the whole of what it can do. To check them later, click the key in the list or choose **View Grants** from its menu.

**3. Create the key**

Give it a description that says where it will be used, then copy the key — it is shown once.

### Creating a user key

**1. Select User tokens**

On the **Authorization Options** card, choose the **User tokens** segment, then **Create New User Token**.

**2. Pick the user**

Admins choose which user the key belongs to. Anyone else creating a key creates it for themselves.

**3. Choose its permissions**

Every REST API and MCP permission the user holds starts selected. Untick anything the key shouldn't be able to do. Permissions the user doesn't hold can't be selected.

**4. Create the key**

Give it a description, then copy the key — it is shown once.

Prefer user keys over account keys where you can: a user key never sees more than that person sees.

## What a key can reach

The two key types are gated differently, which matters when a key authenticates fine but a whole surface is closed to it:

* **User keys carry scopes.** A key needs the `REST` scope to work against the REST API and the `MCP` scope to work against the MCP server. A key without the right scope is rejected as unauthenticated, even though the key itself is valid. A key created in the web app gets the scope for each surface you selected permissions on, or both scopes on accounts without granular permissions.
* **Account keys carry no scopes.** They work on both surfaces, but only while the account has the **REST API module** enabled — the same module gates account-key access to REST *and* to MCP.

Underneath either, per-resource permissions still apply. See [Errors and permissions](https://docs.prophia.com/api-reference/v2/concepts/errors-and-permissions.md) for the capabilities model.

> [!WARNING]
>
> Treat API keys like passwords: use one key per application, and revoke keys you no longer use. A key is shown once at creation — store it in your secrets manager.

## Sending the key

The REST API accepts the key three ways — the header forms are preferred:

```bash theme={null}
curl https://api.prophia.com/rest/v2/accounts/{accountId}/properties \
  -H "X-API-Key: <your-api-key>"
```

```bash theme={null}
curl https://api.prophia.com/rest/v2/accounts/{accountId}/properties \
  -H "Authorization: Bearer <your-api-key>"
```

A `?api_key=` query parameter is also accepted, but avoid it — URLs end up in logs.

> [!NOTE]
>
> JWTs from the Prophia web session are **not** accepted on `/rest` endpoints. If you send one you'll get `401 — JWT authentication is not supported. Use an API key.`

## Errors you'll see

| Status | Meaning |
| - | - |
| `401` | A JWT where a key was expected; the body carries only `error` |
| `403` | No key, an unknown or revoked key, a user key without the scope for the surface you're calling — or a valid key that lacks a capability (e.g. reading documents) or access to that account |
| `404` | Resource isn't in the account your key can see |

For the full status table, the error body, and the capabilities model behind `403` — what each key can read and write, and how `include=` affects the check — see [Errors and permissions](https://docs.prophia.com/api-reference/v2/concepts/errors-and-permissions.md).

## Writing as well as reading

A key that reads your portfolio cannot write to it by default. `POST`, `PATCH`, and `DELETE` need the account's REST API write module enabled on top of the key's own write capability — see [Write access](https://docs.prophia.com/developers/write-access.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.