# Customer.io auth.md
How agents register with and authenticate to Customer.io. Customer.io is a
customer engagement platform; agents operate it two ways — the **MCP Server**
(recommended for AI tools) or the **REST APIs**.

This file is published at the apex domain as a product-level entry point.
The authoritative OAuth infrastructure lives on the MCP host (mcp.customer.io);
links in the Discovery documents section below point there directly.

## Authentication methods
- Customer.io MCP uses OAuth 2.0 authorization code flow with dynamic client registration. See [Customer.io MCP setup](https://docs.customer.io/ai/mcp/get-started/).
- Customer.io App API requests use bearer App API keys created in Customer.io account settings.
- Customer.io Track API and Pipelines API requests use workspace credentials documented in the API reference.

## Discovery documents
- OAuth authorization server metadata: https://mcp.customer.io/.well-known/oauth-authorization-server
- OAuth protected resource metadata: https://mcp.customer.io/.well-known/oauth-protected-resource
- API catalog: https://customer.io/.well-known/api-catalog
- MCP server card: https://customer.io/.well-known/mcp/server-card.json

## Registration
For MCP clients, register directly with the Customer.io MCP authorization server at https://mcp.customer.io/oauth2/register.
For API access, create credentials in Customer.io:
- App API keys: `https://fly.customer.io/settings/api_credentials?keyType=app`
- Workspace credentials for Track and Pipelines APIs: follow the setup instructions in the relevant API reference.

**Supported methods:** OAuth 2.0 (MCP Server); HTTP Basic and Bearer token
(REST APIs) — see below.

**Credential use:** Present the credential on every request — the OAuth access
token (MCP) or the API key via the `Authorization` header. Treat all
credentials as secrets; never embed them in client-side code or commit them to
source control.

## MCP Server (recommended for AI assistants)
The Customer.io MCP Server connects AI tools like Claude and Cursor directly to
a Customer.io workspace — creating segments, building campaigns, and pulling
analytics without leaving the assistant.
- MCP Server docs: https://docs.customer.io/ai/mcp/
- Using Customer.io with LLMs: https://docs.customer.io/ai/cio-with-llms/

## REST APIs
| API | Use it for | Authentication |
| --- | --- | --- |
| Track API | Ingesting people, events, and devices | HTTP Basic (Site ID + Track API Key) |
| App API | Triggering broadcasts / transactional messages, reading data | Bearer token (App API Key) |
| Pipelines (CDP) API | Collecting and routing event data | HTTP Basic (API Key) |
- API reference: https://docs.customer.io/integrations/api/customerio-apis

Customer.io operates in **US and EU regions**. Use the region-specific host
that matches the workspace (for example `https://api.customer.io` for the US
region, with an EU equivalent). See the API reference for exact regional
endpoints.

API keys are created per workspace in the Customer.io UI. Treat them as
secrets — never embed them in client-side code or commit them to source
control.