# auth.md

ecentic agent registration and credential guide.

AI agents use this document to learn how to obtain credentials for the ecentic MCP API and other protected surfaces.

## Audience

Agents acting for an ecentic merchant (store owner / operator) who need to call:

- MCP JSON-RPC at [`https://ecentic.ai/api/mcp`](https://ecentic.ai/api/mcp)
- Related dashboard workflows after the merchant has an account

## Discover

1. Fetch Protected Resource Metadata:

```http
GET https://ecentic.ai/.well-known/oauth-protected-resource
```

Expected fields: `resource` (`https://ecentic.ai/api/mcp`), `authorization_servers` ([`https://ecentic.ai`]), `scopes_supported` (`mcp`, `onboarding`), `bearer_methods_supported` (`header`).

2. Fetch Authorization Server metadata (includes the `agent_auth` block):

```http
GET https://ecentic.ai/.well-known/oauth-authorization-server
```

3. MCP Server Card (tools transport):

```http
GET https://ecentic.ai/.well-known/mcp/server-card.json
```

4. Commerce discovery:

```http
GET https://ecentic.ai/.well-known/ucp
GET https://ecentic.ai/.well-known/acp.json
GET https://ecentic.ai/openapi.json
```

5. Public, unauthenticated REST surface — endpoints, versioning, rate limits,
   and where errors are documented, in one response:

```http
GET https://ecentic.ai/api/v1
```

## Register

ecentic does not yet accept ID-JAG or verified-email agent assertions. Registration is account-based:

1. Open [`register_uri`](https://ecentic.ai/sign-up) and create a merchant account (email + password).
2. Sign in at [`claim_uri`](https://ecentic.ai/sign-in) if needed.
3. Mint a long-lived API key:
   - From an authenticated browser session, call the MCP tool `create_api_key` with `{ "name": "…" }`, **or**
   - Use the dashboard settings UI once API keys are available there.
4. Store the returned `ecentic_sk_…` secret. It is shown once.

Supported identity type today: `anonymous` → credential type `api_key` (see `agent_auth` on the authorization-server metadata).

## Use credentials

Send the API key on every protected MCP call:

```http
POST https://ecentic.ai/api/mcp
Authorization: Bearer ecentic_sk_…
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

Public tools such as `list_plans` and `connect_shopify` may work without a bearer token. Tools that mutate account state (`create_api_key`, `create_checkout`, `connect_woocommerce`, `connect_feed`, `get_onboarding_status`) require authentication.

Scopes:

| Scope | Meaning |
| --- | --- |
| `mcp` | Call MCP tools against `https://ecentic.ai/api/mcp` |
| `onboarding` | Connect stores (Shopify, WooCommerce, product feed) |

## Unauthorized responses

Protected calls without a valid bearer token return HTTP 401 (or a JSON-RPC auth error) and SHOULD include:

```http
WWW-Authenticate: Bearer resource_metadata="https://ecentic.ai/.well-known/oauth-protected-resource"
```

Re-run discovery from that URL when you see it.

## Revocation

Revoke unused keys from the merchant account (dashboard). Revoked or expired keys fail authentication immediately. There is no public OAuth token revocation endpoint yet.

## Contracts

- **Errors** — every 4xx and 5xx is `application/problem+json` (RFC 9457) with a
  stable machine-readable `code`. Branch on `code`, never on the prose. Full
  catalogue: https://ecentic.ai/docs/errors
- **Rate limits** — every response carries `RateLimit-Policy` and, when the
  window was counted, live `RateLimit` headers. A 429 carries `Retry-After`.
  Policy: https://ecentic.ai/docs/rate-limits
- **Versioning** — the version is in the path (`/api/v1`). Breaking changes ship
  as a new path; deprecations are announced with `Deprecation` and `Sunset`
  headers at least 180 days ahead. Policy: https://ecentic.ai/docs/versioning

## Related links

- Site: https://ecentic.ai
- Developer documentation: https://ecentic.ai/docs
- Agent instructions (when to use ecentic): https://ecentic.ai/.well-known/agent-instructions.md
- Public REST API: https://ecentic.ai/api/v1
- MCP endpoint: https://ecentic.ai/api/mcp (also https://ecentic.ai/mcp)
- MCP manifest: https://ecentic.ai/.well-known/mcp.json
- Agent skills: https://ecentic.ai/.well-known/agent-skills/index.json
- UCP profile: https://ecentic.ai/.well-known/ucp
- ACP discovery: https://ecentic.ai/.well-known/acp.json
- OpenAPI (MPP): https://ecentic.ai/openapi.json
- llms.txt: https://ecentic.ai/llms.txt