# DIDWW authentication

REST API v3 uses API keys. MCP uses OAuth 2.0. These credentials are not interchangeable. Never place passwords, API keys, authorization codes, access tokens, refresh tokens, or two-factor codes in an AI conversation.

## Step 1 — Discover

### REST API v3

| Resource | URL |
|---|---|
| Production API | `https://api.didww.com/v3` |
| Sandbox API | `https://sandbox-api.didww.com/v3` |
| Versioning | https://doc.didww.com/api3/api-versioning.html |
| Authentication | https://doc.didww.com/api3/2026-04-16/authentication.html |
| Sandbox guide | https://doc.didww.com/api3/sandbox.html |
| OpenAPI discovery | https://www.didww.com/.well-known/openapi.json |
| OpenAPI JSON | https://doc.didww.com/openapi/2026-04-16/v3_api.json |

API version `2026-04-16` uses `Api-Key: YOUR_API_KEY`. Do not add a `Bearer` prefix. For another dated version, follow that version's documentation and OpenAPI security scheme.

### MCP

MCP server: `https://api.didww.com/mcp`

An unauthenticated request returns:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.didww.com/.well-known/oauth-protected-resource/mcp"
```

Fetch the advertised `oauth-protected-resource` metadata, read `authorization_servers`, then fetch the advertised `oauth-authorization-server` metadata. Use its live authorization, token, and registration endpoints.

Follow the live authorization-server metadata. WorkOS-specific `agent_auth`, `identity_endpoint`, `identity_assertion`, `service_auth`, anonymous Agent Auth, and `id-jag` are not part of the currently published flow. Do not construct endpoints or flows that are not advertised.

## Step 2 — Pick a method

| Use | Method |
|---|---|
| Production REST API | Production API key |
| Sandbox REST API | Sandbox API key |
| Another REST version | Method documented for that version |
| MCP | OAuth 2.0 through a compatible MCP client |

Production and Sandbox accounts and keys are separate.

## Step 3 — Register

For REST:

1. Sign in at `https://my.didww.com/` or `https://my-sandbox.didww.com/`.
2. Open **API → DIDWW API 3**.
3. Create and securely store an API key. Restrict its source IP addresses if required.

For MCP, connect a compatible client to `https://api.didww.com/mcp`. The client retrieves live OAuth metadata and uses its advertised `registration_endpoint`. The user signs in on the authorization page and approves or rejects access. OAuth dynamic client registration is not WorkOS Agent Auth registration.

## Step 4 — Claim

A separate WorkOS Agent Auth claim ceremony is not part of the published flow. REST access belongs to the account that creates the API key. MCP access is approved through browser-based OAuth consent. Do not invent a `claim_endpoint`, claim code, or polling flow.

## Step 5 — Exchange

REST API version `2026-04-16` has no credential exchange; use its API key directly.

For MCP, the client performs the advertised `authorization_code` flow with S256 PKCE and exchanges the code at the live `token_endpoint`. Request `mcp_access` only while it is advertised. The client must handle codes and tokens securely.

## Step 6 — Use the access_token

REST example:

```bash
curl https://api.didww.com/v3/countries \
  -H "Api-Key: YOUR_API_KEY" \
  -H "X-DIDWW-API-Version: 2026-04-16" \
  -H "Accept: application/vnd.api+json"
```

For MCP, the client sends `Authorization: Bearer <access_token>` to `https://api.didww.com/mcp` and manages token storage and refresh using the live metadata.

## Errors

- REST `401`: check the key, environment, version, key status, and IP restrictions.
- REST `403`: the account is not permitted to perform the operation.
- REST `429`: wait before retrying and reduce the request rate.
- MCP `401` or `invalid_token`: let the client refresh or repeat browser authorization.
- Rejected scope: retrieve live metadata and request only advertised scopes.

Do not continuously retry authentication failures.

## Revocation

For REST, remove or rotate the key in the Production or Sandbox User Panel where it was created.

For MCP, open **Account Settings → MCP Clients** in the User Panel and revoke one connection or all connections. Reconnect by repeating browser authorization.

Related documentation:

- https://doc.didww.com/api3/configuration.html
- https://doc.didww.com/api3/sandbox.html
- https://doc.didww.com/mcp/connection-details.html
- https://doc.didww.com/mcp/troubleshooting.html