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

# Authentication

> OAuth scopes a connection to one person; an API key scopes it to the whole workspace.

The NeetoDesk MCP server accepts two credentials, and the choice between them decides what the
assistant can reach. It is a permissions boundary, not a matter of which is easier to set up.

|            | OAuth                              | API key                          |
| ---------- | ---------------------------------- | -------------------------------- |
| Scope      | The person who approved it         | The whole workspace              |
| Identity   | A NeetoDesk user                   | None                             |
| Set up by  | Pasting the server URL             | Pasting a key into a config file |
| Revoked by | Signing out, or revoking the grant | Deleting the key                 |

Both are presented the same way on the wire, as `Authorization: Bearer <token>`. The server
works out which one it is holding.

## OAuth, scoped to you

An OAuth token resolves to a NeetoDesk user, so every request the assistant makes is checked
against that person's role, exactly as it would be in the web app. Both listings and
single-record reads are filtered: an agent restricted to their own tickets gets a ticket list
narrowed to those tickets, and asking for a ticket outside that set fails rather than returning
it.

This is the same boundary the [CLI](/cli/authentication) applies, and it is the reason to prefer
OAuth unless you specifically need workspace-wide access.

### Signing in

<Steps>
  <Step title="Add the server">
    Give your client the server URL `https://connect.neetodesk.com/mcp/messages` with no
    credential attached. [Connect](/mcp/connect) has the exact steps per client.
  </Step>

  <Step title="Approve the connection">
    The client opens NeetoDesk in a browser. Sign in if you are not already.
  </Step>

  <Step title="Pick the workspace">
    If your account belongs to more than one NeetoDesk workspace, you are asked which one the
    connection is for. The grant covers the workspace you pick.
  </Step>
</Steps>

The assistant refreshes the token on its own once it expires. You only sign in again if the
grant is revoked.

### What the server advertises

The server publishes standard metadata at
`https://connect.neetodesk.com/.well-known/oauth-authorization-server`:

|              |                                             |
| ------------ | ------------------------------------------- |
| Grant types  | `authorization_code`, `refresh_token`       |
| PKCE         | `S256`                                      |
| Scopes       | `read`, `write`, `delete`, `offline_access` |
| Registration | Dynamic, at `/mcp/oauth/register`           |
| Revocation   | `/mcp/oauth/revoke`                         |

Dynamic client registration accepts loopback redirect URIs, so terminal clients such as Claude
Code, Codex and Gemini CLI can complete the flow the same way a browser client does.

## API key, scoped to the workspace

An API key carries no identity. The server resolves it to an organization rather than a user, so
the per-user permission checks do not apply and the connection can reach everything in the
workspace.

Use a key when the connection is meant to act for the workspace rather than for a person, such
as a shared automation. Avoid it when a specific agent is the one asking, because it hands that
agent more reach than their role would allow.

<Warning>
  An API key grants workspace-wide access to tickets and customer data. Treat it like a
  password: keep it out of version control, and generate a separate key per integration so a
  single one can be revoked without disturbing the rest.
</Warning>

Generate a key from your workspace admin panel. See the
[API keys help article](https://help.neetodesk.com/articles/api-keys) for the steps, and
[Connect](/mcp/connect) for where to paste it.

With a key you can address your workspace directly at
`https://<your-subdomain>.neetodesk.com/mcp/messages`, which skips the workspace picker since
the subdomain already names the workspace.

## How NeetoDesk's three interfaces compare

|            | REST API             | CLI                           | MCP                          |
| ---------- | -------------------- | ----------------------------- | ---------------------------- |
| Credential | API key              | Browser sign-in               | OAuth or API key             |
| Scope      | Whole workspace      | The person signed in          | The person, or the workspace |
| Header     | `X-Api-Key`          | Session token                 | `Authorization: Bearer`      |
| Suits      | Backend integrations | Interactive and scripted work | AI assistants                |

See [API authentication](/getting-started/authentication) and
[CLI authentication](/cli/authentication) for the other two.