# Authentication

The ABsmartly MCP server supports two authentication methods. Both are configured per client — there are no server-side secrets, so credentials are always provided by your MCP client and isolated per connection. Your instance's `/mcp` endpoint can also accept [federated OIDC tokens](#federated-oidc-tokens-eg-microsoft-entra-id), for example from Microsoft Entra ID, sent by your own backend applications.

| Method                   | Best for                                                                                              | How it works                                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **API Key**              | Programmatic access, CI/CD, headless agents                                                           | Pass the key in HTTP headers or via the URL                                                             |
| **OAuth**                | Interactive use in Claude Desktop, Cursor, the web, etc.                                              | Browser-based login via your ABsmartly SAML/SSO or password                                             |
| **Federated OIDC token** | Your own backend agent acting for users signed in to your identity provider (e.g. Microsoft Entra ID) | Your backend sends an access token from your identity provider as a `Bearer` token (enabled on request) |

## API key

API keys are issued from your ABsmartly instance under **Settings → API Keys**. They authenticate every request and identify which ABsmartly account the MCP session belongs to.

### Where to pass the key

Depending on the client, the API key is supplied as either:

* An HTTP header (`Authorization: …` plus `x-absmartly-endpoint: …`), or
* A query string parameter on the connection URL (`?api_key=YOUR_API_KEY&absmartly-endpoint=https://your-instance.absmartly.com`).

See the [Setup](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/setup.md) guide for the exact configuration per client.

### Authorization header formats

When using API key authentication, these header formats are all supported:

| Format              | Example                                           |
| ------------------- | ------------------------------------------------- |
| Simple API key      | `Authorization: BxYKd1U2...`                      |
| Explicit `Api-Key`  | `Authorization: Api-Key BxYKd1U2...`              |
| Subdomain shorthand | `Authorization: demo-1 BxYKd1U2...`               |
| Full domain         | `Authorization: demo-1.absmartly.com BxYKd1U2...` |

The **subdomain shorthand** auto-constructs the endpoint as `https://<subdomain>.absmartly.com/v1`, so you don't need to send a separate `x-absmartly-endpoint` header.

### API keys on your instance's `/mcp` endpoint

When you connect to `https://your-instance.absmartly.com/mcp` directly, the instance is already known, so only the key is needed:

```text
Authorization: Api-Key YOUR_API_KEY
```

## OAuth

OAuth uses your existing ABsmartly login (SAML, SSO or email and password). This is the recommended method for interactive clients like Claude Desktop, Cursor, VS Code or ChatGPT.

The first time the client connects, it opens a browser window. On the hosted server, you first review the **Authorize Access** consent page for your instance URL and click **Approve**, then sign in to your ABsmartly instance. On your instance's own `/mcp` endpoint, you sign in first and then approve the consent page. The client then receives a token and the MCP connection is established. Later connections reuse the token until it expires or your ABsmartly session ends.

There are two OAuth-enabled MCP URLs:

| URL                                       | How OAuth works                                                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `https://mcp.absmartly.com/mcp` (hosted)  | The hosted server signs you in through your instance and issues its own access token (1 hour) and refresh token (30 days) to the client.                                         |
| `https://your-instance.absmartly.com/mcp` | Your instance is the OAuth server. The client receives a token tied to your browser session, which expires after 24 hours without use. Signing out of ABsmartly ends its access. |

Every OAuth connection uses the authorization code flow with PKCE (`S256`). For the full sequence, the endpoints involved and the ways an MCP client can be registered, see [OAuth & Client Registration](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md).

### Specifying the instance URL

On the hosted server, OAuth needs to know which ABsmartly instance to sign you in to. You can provide this in either of two ways:

* Add `?absmartly-endpoint=https://your-instance.absmartly.com` to the MCP URL, or
* Omit it — the OAuth flow asks you for the URL in the browser before login.

When you connect to `https://your-instance.absmartly.com/mcp` directly, the instance is implied by the URL.

### Supported clients

Most MCP clients are accepted automatically, either through a trusted client metadata document or through dynamic client registration with an allowlisted redirect URI. If your client is rejected, use an API key instead, or see [Your client isn't on the list?](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md#your-client-isnt-on-the-list).

## Federated OIDC tokens (e.g. Microsoft Entra ID)

If you run your own backend agent or application for users who are signed in to your OpenID Connect identity provider, it can call your instance's `/mcp` endpoint with an access token issued by that provider for ABsmartly, obtained for example through the On-Behalf-Of flow or token exchange. Each call acts as the matching ABsmartly user, with that user's permissions. This is enabled per instance by ABsmartly support.

For `/mcp`, the token must carry the MCP scope, by convention `mcp.access`. Federated tokens work only on your instance's own `/mcp` endpoint, not on the hosted server at `mcp.absmartly.com`. The same kind of token can also be enabled for direct REST API calls, with a separate scope.

* [Federated OIDC access tokens](https://docs.absmartly.com/docs/APIs-and-SDKs/Federated-Authentication/federated-oidc-tokens.md) — how it works, the token requirements, calling `/mcp` and `/v1`, and the errors
* [Microsoft Entra ID](https://docs.absmartly.com/docs/APIs-and-SDKs/Federated-Authentication/microsoft-entra-id.md) — step-by-step setup for Entra ID

## Local stdio (CLI credentials)

When running the server locally with `npx @absmartly/mcp`, authentication uses your ABsmartly CLI configuration and macOS Keychain credentials. Select a profile with `--profile=<name>` (for example, `--profile=production`).

## Security model

* **No server-side secrets** — credentials are always provided by the MCP client.
* **Session isolation** — each connection has its own credentials.
* **OAuth protection** — API key sessions block OAuth discovery to prevent authentication-method confusion.
* **Restricted OAuth clients** — only trusted clients and allowlisted redirect URIs can receive OAuth access, and every new client is shown on a consent page first (see [OAuth & Client Registration](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md)).
* **PKCE required** — OAuth requests must use PKCE with `S256`.
* **Destructive action confirmation** — destructive operations such as `start`, `stop`, `archive` and `delete` ask you to confirm before they run, on every transport (see the [Tools Reference](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/tools-reference.md#execute_command)).
* **API error surfacing** — validation errors from the API are returned with full detail so the assistant can correct them.

## Checking who you are

Once connected, you can confirm authentication and identity at any time with the `get_auth_status` tool:

```text
Are we authenticated?
```

The response includes the authenticated email, name, ABsmartly endpoint and the authentication type in use (`API Key` or `OAuth`).
