Authentication

How to authenticate connections to your DataGrout server

DataGrout supports three authentication methods: access tokens, mutual TLS, and OAuth 2.1. If you use the Conduit SDK, authentication is handled for you – pass your credentials to the ClientBuilder and the SDK manages the rest.

Conduit SDK (Recommended)

The Conduit SDK handles authentication automatically. You configure it once and never manage headers, tokens, or certificates manually.

from datagrout_conduit import ClientBuilder

# Bearer token
client = ClientBuilder() \
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp") \
    .auth_bearer("your-token") \
    .build()

# Mutual TLS
client = ClientBuilder() \
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp") \
    .auth_mtls(ClientCert.from_paths("client.crt", "client.key", "ca.crt")) \
    .build()

# OAuth 2.1
client = ClientBuilder() \
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp") \
    .auth_oauth("https://auth.example.com/.well-known/oauth-authorization-server") \
    .build()

See Conduit SDK for full setup.

Access Tokens (Bearer)

The simplest method. Create a token in the UI, pass it in the Authorization header.

Create a Token

  1. Open the server dropdown and click the Settings icon
  2. Go to the Authentication tab
  3. Click Create Access Token
  4. Give it a name (optional)
  5. Copy the token immediately

Use with cURL

Use the /rpc endpoint for stateless HTTP requests:

curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}'

The MCP endpoint (/mcp) also accepts bearer tokens, but requires SSE initialization. Use /rpc for simple testing.

Token Management

  • Tokens are listed in Settings > Authentication
  • Click Delete to revoke a token immediately
  • Use separate tokens per agent or environment
  • Store tokens in environment variables, not code

Mutual TLS (mTLS)

Certificate-based authentication for production deployments. The client certificate is the credential – no bearer token needed after the initial bootstrap.

Bootstrapping with the Conduit SDK

The Conduit SDK handles the entire mTLS bootstrap process automatically. You do not manage raw certificates — the SDK generates a key pair, registers with the DataGrout CA, receives a signed certificate, and stores everything in ~/.conduit/. Subsequent connections use the stored identity with no credentials required.

Python

from datagrout.conduit import Client

# First run: bootstrap with a token
client = await Client.bootstrap_identity(
    url="https://gateway.datagrout.ai/servers/YOUR_UUID/mcp",
    auth_token="your-access-token",
    name="my-agent",
)

# Or bootstrap with OAuth 2.1 client_credentials
client = await Client.bootstrap_identity_oauth(
    url="https://gateway.datagrout.ai/servers/YOUR_UUID/mcp",
    client_id="my_client_id",
    client_secret="my_client_secret",
    name="my-agent",
)

# All subsequent runs: identity auto-discovered from ~/.conduit/
client = Client("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp")

TypeScript

import { Client } from '@datagrout/conduit';

// First run: bootstrap with a token
const client = await Client.bootstrapIdentity({
    url: 'https://gateway.datagrout.ai/servers/YOUR_UUID/mcp',
    authToken: 'your-access-token',
    name: 'my-agent',
});

// Or bootstrap with OAuth 2.1 client_credentials
const client = await Client.bootstrapIdentityOAuth({
    url: 'https://gateway.datagrout.ai/servers/YOUR_UUID/mcp',
    clientId: 'my_client_id',
    clientSecret: 'my_client_secret',
    name: 'my-agent',
});

// All subsequent runs: identity auto-discovered from ~/.conduit/
const client = new Client('https://gateway.datagrout.ai/servers/YOUR_UUID/mcp');
await client.connect();

Rust

// First run: bootstrap
let client = ClientBuilder::new()
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp")
    .bootstrap_identity("your-access-token", "my-agent")
    .await?
    .build()?;

// Subsequent runs: auto-discovered from ~/.conduit/
let client = ClientBuilder::new()
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp")
    .build()?;

Identity Auto-Discovery

The Conduit SDK searches for identity files automatically in this order:

  1. CONDUIT_MTLS_CERT + CONDUIT_MTLS_KEY environment variables (inline PEM strings)
  2. CONDUIT_IDENTITY_DIR environment variable (directory containing identity.pem + identity_key.pem)
  3. ~/.conduit/identity.pem + ~/.conduit/identity_key.pem
  4. .conduit/ relative to the current working directory

For DataGrout URLs, auto-discovery runs silently. For other URLs, set identity_auto=True (Python) or .with_identity_auto() (Rust).

Multiple Agents on One Machine

Use identity_dir to give each agent its own certificate:

client = Client(
    "https://gateway.datagrout.ai/servers/YOUR_UUID/mcp",
    identity_dir="/opt/agents/agent-a/.conduit",
    identity_auto=True,
)

Or set the CONDUIT_IDENTITY_DIR environment variable per process.

Use with cURL

curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  --cert ~/.conduit/identity.pem \
  --key ~/.conduit/identity_key.pem \
  --cacert ~/.conduit/ca.pem \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}'

Certificate Management

  • Certificates are stored in ~/.conduit/ by default (or the configured identity_dir)
  • The SDK checks expiry and warns when rotation is needed
  • Rotate certificates via rotate_identity() – uses the existing cert for authentication (no token required)
  • Revoke certificates in Settings > Authentication when agents are decommissioned

OAuth 2.1

For user-facing applications where users delegate access to your agent.

Grant Types

  • Client Credentials: Machine-to-machine, no user context
  • Authorization Code + PKCE: User delegates access to your app

Setup

  1. Go to Settings > Authentication
  2. Create an OAuth client with redirect URIs and scopes
  3. Save the client ID and secret

Client Credentials Flow

Request an access token:

curl -X POST https://gateway.datagrout.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Use the returned access token as a bearer token. Tokens are short-lived and must be refreshed.

Authorization Code Flow

  1. Redirect the user to the DataGrout authorization endpoint
  2. User approves access
  3. Exchange the authorization code for an access token
  4. Use the access token as a bearer token

The Conduit SDK handles the full OAuth flow automatically when configured with .auth_oauth().

Which Method to Use

Method Best For
Access Tokens Development, scripts, internal agents
mTLS Production agents, enterprise deployments
OAuth 2.1 User-facing apps, third-party integrations

Related