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

# Authentication & Security

## Base URL

All API calls are made against:

```
https://mcp.runalloy.com
```

There are two categories of endpoints:

* **Server Management API** (`/api/servers/...`) – Create, list, update, or delete MCP servers.
* **MCP Protocol API** (`/mcp/...`) – Called by your assistant to invoke tools and connectors via JSON‑RPC.

## API Keys and User IDs

Management requests require two headers:

```
Authorization: Bearer <API_KEY>
x-alloy-userid: <USER_ID>
```

* API keys are generated in the Alloy dashboard and scoped to your account.
* Each API key is tied to a specific user ID to support multi-tenant architectures.
* Do not expose API keys in client-side code or public repositories.
* Rotate keys periodically for security.

## Token URLs vs API Authentication

MCP protocol calls support two authentication methods:

### Token URL

Use the tokenized URL returned when creating the server:

```
/mcp/{serverId}/{accessToken}
```

* No additional headers required.
* Ideal for embedding in assistants or simple client use cases.

### API Authentication

Call the following endpoint:

```
/mcp/{serverId}
```

Include the same headers used for management:

```
Authorization: Bearer <API_KEY>
x-alloy-userid: <USER_ID>
```

* Ideal for B2B scenarios where you need dynamic management of multiple users within an organization
* Allows for token rotation and additional control
* Enables per-user isolation without creating separate servers
* Requires clients to sign each request

### Optional Headers

* `x-alloy-user-token` (JWT): Isolates requests by end user.
* `x-credential-id`: Forces use of a specific credential.
* `x-redirect-uri`: Used in OAuth flows for post-auth redirection.

## Authentication Request Flow

```mermaid mermaid theme={null}
sequenceDiagram
    participant C as MCP Client
    participant M as MCP Server
    participant A as Alloy API
    participant P as Platform (e.g., Slack)

    C->>M: MCP Request<br/>(tools/call)
    activate M
    M->>M: Validate Auth
    M->>M: Check Rate Limits
    M->>M: Apply Restrictions
    M->>A: API Request
    activate A
    A->>A: Decrypt Credentials
    A->>P: Platform API Call
    activate P
    P-->>A: Platform Response
    deactivate P
    A-->>M: Formatted Response
    deactivate A
    M-->>C: MCP Response
    deactivate M
```

This diagram shows the complete authentication and request flow:

1. **Authentication**: The MCP Server validates the request authentication
2. **Rate Limiting**: Checks against rate limits (100 req/min default)
3. **Restrictions**: Applies any configured access restrictions
4. **API Request**: Makes authenticated request to Alloy API
5. **Credential Decryption**: Alloy decrypts stored platform credentials
6. **Platform Call**: Executes the action on the external platform
7. **Response**: Returns formatted response to MCP client

## Best Practices

* **Least privilege**: Restrict access to only the connectors and actions the server needs.
* **Rotate secrets**: Periodically regenerate API keys and server tokens.
* **Isolate users**: Use JWTs (`x-alloy-user-token`) to segregate end-user actions on shared servers.
* **Store secrets securely**: Use environment variables or secret managers. Never hardcode credentials in code or HTML.