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

# Connections

> Store upstream MCP server credentials securely and route requests through Igris.

# Connections

Connections are encrypted credential vaults for upstream MCP servers. Instead of putting real API keys in your code, you create a connection in Igris that stores the credential securely and gives you a clean gateway URL.

## How Connections Work

```
Without connections:
  Your app → real upstream credential in code → MCP server

With connections:
  Your app → Igris API key only → Igris Gateway → injects real credential → MCP server
```

**Benefits:**

* Real credentials never leave Igris — encrypted at rest with AES-256-GCM
* Rotate credentials instantly without changing any code
* Revoke access by disabling the connection
* Full audit trail of every request per connection

## Create a Connection

In the dashboard: **Governance → Connections → New Connection**

Or via API:

```bash theme={null}
curl -X POST https://api.igrisecurity.com/api/v1/connections \
  -H "Authorization: Bearer ig_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "github-prod",
    "name": "GitHub Production",
    "upstreamUrl": "https://mcp.github.com",
    "authType": "bearer",
    "credential": "ghp_your_github_token"
  }'
```

The credential is encrypted and stored. It will never be returned in any API response.

### Auth Types

Connections support eight authentication types for upstream credential injection:

| Auth Type | Behavior                                                                                                 |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `bearer`  | Injects credential as `Authorization: Bearer <credential>` (default)                                     |
| `header`  | Injects credential as a raw header value with a custom header name (requires `authHeaderName`)           |
| `none`    | No credential injection — upstream doesn't require auth                                                  |
| `oauth`   | OAuth 2.0 client credentials flow — credential is the client secret, fetches access tokens automatically |
| `mtls`    | Mutual TLS — credential is the client private key (PEM); requires a client certificate                   |
| `azure`   | Azure Managed Identity / Entra workload identity token injection                                         |
| `aws`     | AWS SigV4 signing — credential is `ACCESS_KEY_ID:SECRET_ACCESS_KEY`                                      |
| `gcp`     | GCP service account token injection — credential is a service account JSON key                           |

### Custom Auth Headers

Some MCP servers expect credentials in a non-standard header. Use `authType: "header"` with `authHeaderName`:

```bash theme={null}
curl -X POST https://api.igrisecurity.com/api/v1/connections \
  -H "Authorization: Bearer ig_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "custom-api",
    "name": "Custom API",
    "upstreamUrl": "https://my-api.example.com/mcp",
    "authType": "header",
    "authHeaderName": "X-API-Key",
    "credential": "sk_my_secret_key"
  }'
```

This injects the credential as `X-API-Key: sk_my_secret_key` to the upstream server.

## Use a Connection

### With the SDK

```typescript theme={null}
const config = igris.connectHttp("github-prod", {
  user: "alice@company.com",
  metadata: { role: "developer" },
});

// config.baseUrl = "https://api.igrisecurity.com/v1/mcp/github-prod"
// config.apiKey  = "ig_..."   (set as Authorization: Bearer when calling the gateway)
// config.headers = { "X-Igris-Trace-Id": "...", "X-Igris-User": "...", "X-Igris-Metadata": "..." }
```

### Direct MCP Client Config

```json theme={null}
{
  "mcpServers": {
    "github": {
      "url": "https://api.igrisecurity.com/v1/mcp/github-prod",
      "headers": {
        "Authorization": "Bearer ig_your_api_key"
      }
    }
  }
}
```

## Credential Injection

When the gateway receives a request, it:

1. Strips your Igris API key (never forwarded upstream)
2. Decrypts the connection's credential
3. Injects it using the configured auth type:
   * **bearer**: `Authorization: Bearer <credential>`
   * **header**: `<authHeaderName>: <credential>`
   * **none**: no credential injected

The upstream server only sees its own credential. Your users only see the Igris API key.

## Rotate Credentials

Update a credential without changing any SDK configs:

```bash theme={null}
curl -X POST https://api.igrisecurity.com/api/v1/connections/github-prod/rotate \
  -H "Authorization: Bearer ig_..." \
  -H "Content-Type: application/json" \
  -d '{ "credential": "ghp_new_token_here" }'
```

All requests immediately use the new credential. Zero downtime.

## Slug Format

Connection slugs must be:

* Lowercase letters, numbers, underscores, hyphens
* 3-64 characters
* Start with a letter or number

Examples: `github-prod`, `slack-mcp`, `analytics01`