Skip to main content
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

1

Open Settings → Developers → API keys

You need settings access in the app; admins have it.
2

Name it, then choose a role, scopes and an expiry

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

Copy the key

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

​
For developers

Send the key as a bearer token on every request:
  • 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.