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

# Authentication

> OAuth consent, build vs use scopes, and API keys for CI

## Interactive OAuth (recommended)

On first connection, the MCP client:

1. Hits the Builder or Runtime URL
2. Receives an authorization challenge
3. Opens a browser consent screen for your EKB account (`/oauth/consent`)
4. Completes an authorization code flow with **PKCE**
5. Calls EKB with a token that represents **you**

You approve either **build** or **use** access depending on which endpoint you connected. Builder and Runtime do **not** share tokens.

### What the consent screen shows

| Scope        | Label on screen               |
| ------------ | ----------------------------- |
| `odin:build` | **Build in your workspace**   |
| `odin:use`   | **Use your agents and tools** |

The screen names the requesting MCP client and lists the permission. Approve or deny explicitly — nothing is granted by default. Denying redirects back to the client with `error=access_denied` so the client does not hang.

Pending consent requests expire. If the page says the request expired or was already used, start again from the MCP client.

## Why two grants

| Grant   | Scope        | Audience       | Typical use                                              |
| ------- | ------------ | -------------- | -------------------------------------------------------- |
| Builder | `odin:build` | `/builder/mcp` | Create/change agents, workflows, tables, interfaces, KBs |
| Runtime | `odin:use`   | `/runtime/mcp` | Ask agents, run published tools, search KB, query tables |

A Runtime token fails if pointed at Builder (and the reverse). “Use my support agent” cannot escalate into “rewrite my agents.”

## What the token can do

Three layers apply:

1. **Audience** — token is valid only for the server you authorized
2. **Scope** — build vs use
3. **Backend allowlist** — only an explicit set of EKB APIs is reachable over MCP

The MCP service holds **no credentials of its own**. Every call forwards your token (or API key). EKB still enforces normal project membership, permissions, publish state, and document Access Tags.

## API keys (headless)

CI and automation cannot complete a browser consent flow. Pass:

```text theme={null}
X-API-KEY: ...
X-API-SECRET: ...
```

| Key type           | Best for                                                                       |
| ------------------ | ------------------------------------------------------------------------------ |
| **User-level**     | `list_odin_projects`, multi-project Runtime, CI that must see several projects |
| **Project-scoped** | Automation locked to a single project                                          |

Example config: [Connect a client](/ekb-as-mcp/connect-a-client#headless-access-ci-and-automation).

Treat API secrets in MCP client config like any other credential — do not commit them to shared repos.

## Security tips

* Connect **Builder** only on clients that should change configuration
* Prefer **Runtime** alone for day-to-day assistants
* Use HTTPS MCP URLs in production
* Rotate API keys used for headless access
* Revoke or reconnect if a laptop / client should no longer have build access
* Remember: Access Tags and project roles still apply to Runtime search and agent answers

## Troubleshooting

| Symptom                                | What to check                                                      |
| -------------------------------------- | ------------------------------------------------------------------ |
| Consent expired                        | Restart from the client; requests are short-lived                  |
| Token works on Runtime but not Builder | Expected — separate grants; connect and approve Builder separately |
| Headless calls fail across projects    | Use a user-level API key                                           |
| Client hangs after deny                | Client should handle `access_denied`; retry connection if needed   |

## Related

* [Overview](/ekb-as-mcp/overview)
* [Connect a client](/ekb-as-mcp/connect-a-client)
* [Builder](/ekb-as-mcp/builder)
* [Runtime](/ekb-as-mcp/runtime)