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

# Authentication

> Authenticate an interactive or headless client to the account-resolved v3 MCP endpoint.

Connect to `https://api.interchange.io/mcp/v3` with OAuth or a supported
API credential. The credential determines the home account, reachable accounts, and
permissions; the URL does not select Buyer or Seller behavior.

* Use OAuth for interactive clients and human-authorized work.
* Use a user API key for simple headless automation, stored in a secret
  manager and sent as `Authorization: Bearer YOUR_API_KEY`. A key acts as its
  owner and is bound to the organization selected when it was created.
* Use an M2M application when your deployed backend requires the OAuth
  `client_credentials` flow. Follow the separate credential and permission
  requirements in the full authentication reference.
* Grant only the permissions the integration needs. A visible tool may still
  refuse a write when the credential lacks the required permission.

Call `get_status` after authentication to verify the selected account and its
readiness. Every authenticated Buyer and Seller Account can connect; individual
operations still require the appropriate permissions and resource access.

An agent should direct a person to **Settings → API Access** to create a user
API key. It cannot retrieve an existing secret, and a long-lived credential
must not pass through chat. Existing organization-owned keys remain supported
during migration; they are not the default for a new integration.

## OAuth resource binding

OAuth discovery for v3 advertises `https://api.interchange.io/mcp/v3` as the
exact protected resource. MCP clients carry that URI through authorization,
token exchange, and refresh. Apostra issues dedicated MCP access and
refresh credentials for that resource; a v3 credential is rejected on another
MCP endpoint or on the REST API.

The protected-resource metadata document is available at
`https://api.interchange.io/.well-known/oauth-protected-resource/mcp/v3`.
Clients should follow the `resource_metadata` URL in the server's
`WWW-Authenticate` challenge instead of constructing it themselves.

<Card title="Full authentication reference" icon="book" href="/v2/authentication#mcp-oauth-resource-binding">
  Review OAuth, user API keys, M2M applications, permissions, and stable
  v2 versioning behavior in the canonical authentication guide.
</Card>