Authentication

Conduit supports two authentication methods for vendor access: API keys and OAuth 2.0 with PKCE. Both produce Bearer tokens used against the gateway.

API Keys

API keys are the simplest way to authenticate. Each key is scoped to your organization and can be created from the dashboard or CLI.

Key format

All API keys follow the format cnd_live_ followed by 32 alphanumeric characters:

cnd_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Key storage

Keys are hashed with SHA-256 before storage. The plaintext is shown only once at creation. If lost, revoke the key and create a new one.

Using API keys

Pass your API key in the Authorization header:

bash

curl -X POST https://gateway.conduitapi.dev/s/mls-org/reso-feed \
  -H "Authorization: Bearer cnd_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Creating and revoking keys

Create via API

POST /api/keys
{ "name": "Production key" }

→ { "id": "uuid", "key": "cnd_live_xxx...", "name": "Production key" }

Create via CLI

conduit keys create --name "Production key"

Revoke

DELETE /api/keys/:id

Takes effect immediately. All inflight requests with this key will fail.

[!]Store keys securely

The full key value is returned only once at creation. Store it in a secrets manager or environment variable. Never commit keys to source control.

OAuth 2.0 (Authorization Code + PKCE)

For applications where users authorize access on behalf of their organization, Conduit implements OAuth 2.0 with PKCE. This is the recommended approach for multi-tenant integrations.

1. Register your client

bash

POST /api/oauth/register
Content-Type: application/json

{
  "client_name": "My Vendor App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}

Returns a client_id for use in subsequent steps.

2. Redirect to authorization

text

GET /api/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://myapp.com/callback&
  code_challenge=BASE64URL_CHALLENGE&
  code_challenge_method=S256&
  scope=mcp:tools

The user signs in and approves access. Conduit redirects back to your redirect_uri with an authorization code.

3. Exchange code for tokens

bash

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
client_id=YOUR_CLIENT_ID&
code_verifier=YOUR_CODE_VERIFIER

Response:

json

{
  "access_token": "cnd_oat_xxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cnd_ort_xxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp:tools"
}

4. Refresh tokens

Access tokens expire after 1 hour. Use the refresh token to obtain new credentials. Refresh tokens are rotated on each use.

bash

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=cnd_ort_xxxxxxxxxxxxxxxxxxxx&
client_id=YOUR_CLIENT_ID

5. Use with the gateway

OAuth access tokens work identically to API keys in the Authorization header:

bash

curl -X POST https://gateway.conduitapi.dev/s/mls-org/reso-feed \
  -H "Authorization: Bearer cnd_oat_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

OAuth Protected Resource Metadata

The gateway publishes OAuth metadata at its well-known endpoint. MCP clients that support RFC 9728 can auto-discover the authorization server:

json

GET https://gateway.conduitapi.dev/.well-known/oauth-protected-resource

{
  "resource": "https://gateway.conduitapi.dev",
  "authorization_servers": ["https://conduitapi.dev"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp:tools"]
}

Next: Gateway Routing →

←Quickstart Gateway Routing→