> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Amazon integrations

> Discover granted Amazon identities and obtain provider access tokens.

## Discover identities

Exchange an API key linked to an M2M client with `amazon-connections:read`, then:

```bash
curl --fail-with-body \
  'https://app.kuudo.com/api/mcp/amazon/identities?provider=amazon_sp_api' \
  --header "Authorization: Bearer ${KUUDO_ACCESS_TOKEN}"
```

The `provider` filter is optional and accepts `amazon_ads` or `amazon_sp_api`.
The response contains an `identities` array. Its `id` values are canonical
authorization IDs; preserve them when requesting tokens.

Only accounts permitted by the live M2M policy and capable of raw-token delivery
are returned. Restricted clients need an effective authorization grant. These
routes require API-key-derived JWTs and reject raw keys and other OAuth bearers.

## Vend an access token

Use `amazon-tokens:vend` and the canonical ID from discovery:

```bash
curl --fail-with-body --request POST \
  "https://app.kuudo.com/api/mcp/amazon/identities/${KUUDO_AUTHORIZATION_ID}/token" \
  --header "Authorization: Bearer ${KUUDO_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"amazon_sp_api"}'
```

The response supplies an **Amazon access token**, `expires_at`, `client_id`,
`region`, and `base_url`, with provider-specific identity or profile fields.
Keep this token on your backend, never log it, and honor `expires_at`. Provider
authorization and commercial entitlements apply in addition to route scope.
Amazon machine responses disable caching.

For Ads, `profile_id` can select a profile. `profileId` is a compatibility alias.
The request body can be omitted when provider/profile selection is unnecessary.

## Configuration errors

Identity listing and token vending return HTTP 503 with
`error.code: M2M_AUTHORIZATION_CONFIGURATION_ERROR` when the active M2M client
has no configured authorization-policy mode. This is nonretryable until the
configuration is repaired. Unexpected server failures retain HTTP 500 with
`error.code: INTERNAL_ERROR`. Classify errors by their code, not message text.
Both responses retain `Cache-Control: no-store`.

## Invite a downstream customer

Authorization invitations are a **development contract pending release qualification**.
When available, your backend creates a link using an API-key-derived JWT with
`authorization-invitations:write` and a required `Idempotency-Key`.

```json
{
  "provider": "amazon_sp_api",
  "externalCustomerReference": "customer_example",
  "options": { "sellingPartnerType": "seller", "marketplace": "uk" }
}
```

For Ads, use `provider: "amazon_ads"` with an optional region of `na`, `eu`, or `fe`.
For SP-API, use `seller` or `vendor` and a documented lowercase marketplace slug.
Omitted choices are collected from the recipient. Fixed choices cannot be overridden.
Unknown fields are rejected.

A new request returns 201 with `authorizationUrl`; eligible idempotent replay
returns 200. Links expire after seven days and are capabilities: distribute them
through your own application and avoid logs/analytics. No automatic email is sent.

Poll the invitation with `authorization-invitations:read`. List responses support
cursor pagination with limits from 1 through 50. Machine reads and cancellation
are limited to the initiating M2M client. GET/list responses never include the link.
Completed status includes `authorizationId`; optional provider metadata requires
an effective grant. Cancelling an unfinished invitation does not revoke a completed
authorization.

Creation does not grant token access. Arrange the appropriate M2M authorization
policy before consuming the resulting identity through discovery and token vending.