> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextlevelmca.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Access and permissions
> Create an API key in Settings, decide what it may see and do with a role and scopes, and revoke it any time.
Anything that connects to NextLevel MCA, whether a script, an integration or an AI assistant, gets its own credential, and every credential is tied to one workspace. API keys are created in the app; assistant connections are approved by the team member who signs in. Both carry two settings that decide what they can do: a **role**, which sets how much they can see and do, and **scopes**, which limit what they may touch.
## Creating an API key
You need settings access in the app; admins have it.
The name shows up in the activity log on anything the key changes, so use something a colleague would recognise ("Website intake", "Underwriting bot"). Role and scopes are explained below. Expiry is optional; an expired key simply stops working.
It is shown once. Afterwards the app shows only the first and last few characters. If you lose it, revoke it and create a new one.
Revoke a key from the same page. Revocation is immediate: the next request with that key is refused.
Treat keys like passwords. Keep them out of browser code and logs, share them only with the people who need them, and revoke any key that may have leaked.
## Roles: how much a connection can see and do
| Role | In one line |
| - | - |
| `admin` | Everything an admin can do in the app, including managing the team and settings. |
| `manager` (default) | Everything except managing the team and changing settings. The right choice for almost every integration. |
| `user` | The standard user's defaults: sees only the deals it created, can create and edit deals and submit them, can log offers but not edit or accept them, has no access to advances or reports, and sees lenders read-only. |
Role also decides who sees personal details. Dates of birth are returned only to `admin` and `manager`. Social security numbers are never returned to anyone: they can be saved through the API, and reads show only the last four digits (`***-**-6789`).
## Scopes: what a connection may touch
A scope is permission for one kind of work. A key with no scopes selected can do everything its role allows; pick scopes to narrow it, for example read-only scopes for a reporting integration, or `businesses:write` and `deals:write` alone for a website intake form. Assistant connections choose scopes on the consent screen when the user signs in.
| Scope | Lets the connection |
| - | - |
| `businesses:read` | Read businesses and their notes, tasks and activity |
| `businesses:write` | Create and update businesses, notes and tasks |
| `people:read` | Read people (contacts and owners) |
| `people:write` | Create and update people |
| `deals:read` | Read deals, submissions and the pipeline |
| `deals:write` | Create and update deals, move stages |
| `documents:read` | Read documents and statement analysis |
| `documents:write` | Upload documents and request documents from merchants |
| `lenders:read` | Read lenders, criteria and lender matches |
| `lenders:write` | Create and update lenders and criteria, including their API integrations |
| `submissions:write` | Submit deals to lenders and withdraw submissions |
| `offers:read` | Read offers |
| `offers:write` | Log and update offers, set the primary offer |
| `advances:read` | Read funded advances and renewal flags |
| `advances:write` | Update advances |
| `portal:send` | Generate and send merchant portal links |
| `webhooks:manage` | Manage webhook subscriptions |
Role and scopes are checked together on every request, so a scope never grants more than the role allows. Two details worth knowing: submissions are read with `deals:read` (there is no `submissions:read`), and a task can be updated with either `businesses:write` or `deals:write`.
## Assistant connections
AI assistants such as Claude and ChatGPT do not use keys. The team member signs in with a one-time emailed code, picks a workspace and approves the scopes; from then on the assistant acts as that person, with their role and their view of the pipeline. Connections are listed and revoked under **Settings → Developers → Connected apps**. See [Security](/developers/mcp/oauth-and-security).
The one exception is a CRM workflow's AI agent. No one is signed in while a workflow runs, so it connects to the MCP server with an API key. See [Connect from CRM workflows](/developers/mcp/connect-from-crm-workflows).
## For developers
Send the key as a bearer token on every request:
```bash theme={null}
curl "https://api.nextlevelmca.com/v1/deals?limit=5" \
-H "Authorization: Bearer nlmca_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```
* Keys look like `nlmca_live_` followed by 32 random characters and are stored only as a hash. They are accepted **only** on `/v1` and the MCP server, where they have the same role and scopes. The app's internal routes reject them, so a leaked key cannot reach anything not documented here.
* A missing, invalid, expired or revoked key returns `401` with `type: "authentication_error"` and `code: "unauthorized"`; the message says which (`"API key has been revoked"`, `"API key has expired"`).
* A key without the scope an endpoint needs returns `403` with `type: "permission_error"`, `code: "missing_scope"` and `param` set to the scope to add. A role without the permission returns `403` with `code: "forbidden"`.
* OAuth access tokens issued to assistant connections are accepted on `/v1` with the same header. They act as the user who approved them, with the scopes from the consent screen. A token issued for the MCP server also works on `/v1`; a token issued for `/v1` (`resource=https://api.nextlevelmca.com`) is not accepted on `/mcp`. Deactivating or removing the user stops their tokens immediately.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.