Amazon integrations

Discover identities

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

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:

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.

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.

{
  "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.