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

# Authentication

> OAuth is scoped to you; an API key is scoped to the whole workspace.

The NeetoInvoice MCP server accepts two credentials. The difference is a permissions boundary,
not a setup preference, so pick deliberately.

|            | OAuth                      | API key                          |
| ---------- | -------------------------- | -------------------------------- |
| Scope      | The person who approved it | The whole workspace              |
| Identity   | A NeetoInvoice user        | None                             |
| Set up by  | Pasting the server URL     | Pasting a key into a config file |
| Revoked by | Revoking the grant         | Revoking the key                 |

With OAuth the assistant acts as you, so every request is filtered through your role's
permissions: you see the clients, projects, and time entries your account can see, and nothing
else. With an API key the assistant acts as the workspace, with no user attached and no role
filtering.

<Warning>
  An API key reaches everything in the workspace, including every user's time entries and the
  payroll and PTO reports. Prefer OAuth unless you specifically need workspace-wide access,
  such as an unattended script.
</Warning>

## OAuth, scoped to you

Supported by clients that can open a browser and complete a redirect.

| Property               | Value                                                  |
| ---------------------- | ------------------------------------------------------ |
| Authorization endpoint | `https://connect.neetoinvoice.com/mcp/oauth/authorize` |
| Token endpoint         | `https://connect.neetoinvoice.com/mcp/oauth/token`     |
| Registration endpoint  | `https://connect.neetoinvoice.com/mcp/oauth/register`  |
| Revocation endpoint    | `https://connect.neetoinvoice.com/mcp/oauth/revoke`    |
| Grant types            | `authorization_code`, `refresh_token`                  |
| PKCE                   | `S256`                                                 |
| Scope                  | `mcp`                                                  |

Clients discover all of this automatically from
`https://connect.neetoinvoice.com/.well-known/oauth-authorization-server`, so you only ever
paste the server URL.

### Signing in

1. Add the server to your assistant using the steps on [Connect](/mcp/connect).
2. The assistant opens a browser at the authorization endpoint.
3. Pick the workspace to grant access to, then approve.
4. The assistant stores the token and refreshes it automatically.

Registration is dynamic, so there is no client ID or secret to create by hand.

### Multiple workspaces

The grant covers the workspace you picked during approval. To reach a second workspace,
approve it as a separate connection. `ListWorkspaces` reports which ones the current
connection can see.

### Revoking

Revoke the grant from your NeetoInvoice profile, or let the client call the revocation
endpoint when you remove the server. Revoking affects only that connection, not your other
sessions.

<Note>
  OAuth currently works with Claude and ChatGPT. Terminal and editor clients register a
  `http://localhost/...` callback, which this deployment does not yet accept, so they
  authenticate with an API key instead. See the support matrix on
  [Connect](/mcp/connect#which-method-does-my-client-use).
</Note>

## API key, scoped to the workspace

The same key the REST API uses. There is no separate credential to create.

### Generating a key

Generate it from your workspace settings.
[Learn how to generate your API key here.](https://help.neetoinvoice.com/articles/api-keys)

<Tip>
  Generate a separate API key for each workspace. A key generated in one workspace will not
  work in another.
</Tip>

### Sending it

Your assistant sends the key on every request as an `Authorization` header. You never type the
header yourself: you paste the key into the assistant's MCP config and the assistant sends it.

```
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  An API key grants access to your workspace's billing and time-tracking data. Treat it like a
  password. MCP config files usually live in your home directory or your repository, so keep
  them out of version control.
</Warning>

### Revoking

Revoke the key in workspace settings. The next request from any assistant configured with it
fails, so revoke the key rather than only deleting the config when you want access to stop.

## How each surface authenticates

| Surface                                     | Credential                             | Acts as                                 |
| ------------------------------------------- | -------------------------------------- | --------------------------------------- |
| [REST API](/getting-started/authentication) | `X-Api-Key` header                     | The workspace, unrestricted by role     |
| [CLI](/cli/authentication)                  | Browser session stored on your machine | You, limited by your role's permissions |
| MCP server (OAuth)                          | `Authorization: Bearer <oauth-token>`  | You, limited by your role's permissions |
| MCP server (API key)                        | `Authorization: Bearer <api-key>`      | The workspace, unrestricted by role     |