Account Linking for MCP Add-ons

Account linking connects a customer's Amazon account to their account in your service. Once linked, every request Alexa sends to your add-on includes an OAuth access token — enabling your service to personalize responses, access user-specific data, and perform authenticated actions on the customer's behalf.

Account linking is optional. If your add-on's tools work the same way for all users — for example, a restaurant search or a general information tool — you don't need it. Only enable account linking if your tools genuinely require user identity to function. Enable it if your add-on accesses user-specific data (order history, preferences, saved addresses), performs write actions on behalf of the customer, or requires authentication before accessing any part of your service.

How account linking works

Account linking for Alexa+ MCP add-ons uses the OAuth 2.1 authentication framework. Before you set up account linking, review the following concepts. Understanding these roles and flows will help you configure your authorization server correctly and avoid common integration mistakes.

What is OAuth 2.1? OAuth 2.1 isn't a completely new protocol — it's OAuth 2.0 with three key changes consolidated from security best practices. For Alexa+ account linking purposes, the practical implication is simple: if your authorization server already supports PKCE S256, you're already OAuth 2.1 compliant. For managed services like Auth0, AWS Cognito, and Okta, enabling PKCE S256 is a single configuration toggle.

OAuth roles

OAuth 2.1 defines four roles. In the context of an Alexa add-on:

Grant types

Alexa+ add-ons support only the Authorization Code Grant. The implicit grant isn't supported for Alexa+ add-ons.

Authorization Code Grant (supported): Alexa obtains an authorization code from your authorization server, exchanges it for access and refresh tokens, and includes the access token in every request sent to your add-on. This is the grant type used by all MCP add-ons.

Implicit Grant (not supported): An alternative grant where the authorization server returns the access token directly after login — no authorization code exchange step. This grant type is less secure and isn't supported.

Codes and tokens

Account linking uses three types of credentials:

Authorization Code: A short-lived code your authorization server issues after the customer logs in. Your server passes this code back to Alexa by including it as a query parameter in the redirect. Alexa then exchanges this code for an access and refresh token pair. The authorization code itself is never used to access customer data directly.

Access Token: A credential issued by your token server when Alexa exchanges the authorization code. After account linking is complete, Alexa includes this access token in every request it sends to your add-on. Your add-on uses it to identify the customer and access their data in your resource server.

Refresh Token: A long-lived credential Alexa uses to request a new access token after the original expires — without asking the customer to log in again. Your token endpoint must return a refresh token alongside every access token. If no refresh token is issued, customers must re-link their account each time the access token expires.

PKCE Code Challenge: For the authorization code grant type, Alexa implements PKCE to prevent authorization code interception attacks. Alexa generates a secret key (code_verifier), encodes it using SHA-256 (code_challenge), and sends the challenge in the authorization request. When requesting a token, Alexa sends the original code_verifier — your server verifies the pair before issuing the access token.

Resource Parameter: The canonical URI of your MCP server. Alexa includes this as a resource parameter in both the authorization request and the token exchange request but not in the token refresh request, so your authorization server knows which resource is being accessed.

URIs for account linking

Three URIs are involved in the account linking flow:

Authorization URI: The URL of your authorization server. Alexa redirects the customer here to log in. Alexa passes the following query parameters when it calls this URI:

Sample authorization request URL:

https://auth.yourservice.com/oauth2/authorize?
  client_id=your-client-id
  &redirect_uri=https%3A%2F%2Falexa.amazon.com%2Fapi%2Fskill%2Flink%2FM3IHEJ1OZMSGZ3
  &response_type=code
  &scope=openid%20your-scope
  &state=abc123
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fyour-mcp-server.com%2Fmcp

Expected redirect response (your server calls this after the customer logs in and approves):

https://alexa.amazon.com/api/skill/link/M3IHEJ1OZMSGZ3?code=SplxlOBeZQQYbYS6WxSbIA&state=abc123

Alexa Redirect URI: The URI your authorization server calls to send the customer back to Alexa after they log in.

Access Token URI: The URL of your token endpoint. After the customer logs in, Alexa makes a POST request to this URI with the authorization code. Your server responds with the access token, refresh token, and expiry in JSON.

Sample token request:

POST https://auth.yourservice.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Falexa.amazon.com%2Fapi%2Fskill%2Flink%2FM3IHEJ1OZMSGZ3
&client_id=your-client-id
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&resource=https%3A%2F%2Fyour-mcp-server.com%2Fmcp

Expected token response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpc..."
}

What Alexa handles vs what you build

Alexa handles the complete customer-facing linking flow. Your responsibilities are limited to your OAuth server and a small amount of server-side configuration.

Alexa handles the following automatically:

1. QR code generation and display on screen devices
2. Push notification to all Alexa endpoints
3. OAuth redirect flow and callback
4. Authorization code exchange for access and refresh tokens
5. Secure token storage
6. Requesting a new access token when needed to fulfill a customer request
7. Re-initiating the account linking flow when a token expires or is revoked

You are responsible for the following:

1. Your OAuth 2.1 authorization server
2. Client ID and client secret
3. PKCE S256 support on your authorization server
4. Hosting a well-known metadata document on your MCP server
5. Returning HTTP 401 or 403 when a tool is called without a valid token
6. Registering all Alexa redirect URIs on your authorization server
7. Static client registration — Dynamic Client Registration (DCR) isn't supported
8. Re-deploying your add-on if your authorization server configuration changes — Alexa caches auth metadata at deploy time and uses that cache at runtime
9. A publicly accessible privacy policy that covers account data usage

Account linking patterns

Before you set up account linking, choose the pattern that matches your service. The pattern determines what your customer sees during the linking flow and what you need to build beyond a standard OAuth server.

All three patterns share the same trigger: a customer makes a request, Alexa invokes an MCP tool that requires authentication, your server returns HTTP 401 or 403, and Alexa initiates the linking flow. The pattern controls what happens next.

Pattern 1 — QR Code / Web OAuth (default)

Every MCP add-on with account linking enabled uses this pattern automatically.

On headless devices: When there's no screen to display a QR code, Alexa automatically sends a push notification to the customer's Alexa mobile app. The customer taps the notification and completes the flow in the app. You don't build anything for this — Alexa handles it entirely.

Pattern 2 — App-to-App (deep-link)

In this scenario, customers scan a QR code raised on Alexa through the conversation view or tap the push notification. Once the customer arrives on your add-on detail page in the Alexa app and initiates account linking, they're deep-linked directly into your native app to approve access — making linking a one-tap process for customers who already have your app installed.

Pattern 3 — Login with Amazon (LWA)

Available if you don't have an existing account system or want to reduce sign-up friction for new customers. Amazon acts as the identity provider — customers log in with their existing Amazon credentials. Your backend uses the returned customer profile to match or create an account automatically.

What you build: LWA integration on your backend to receive the Amazon customer profile and perform account matching or creation.

Benefits of LWA:

1. Customers with an Amazon account can link in seconds — no new password to create for new account creation flows.
2. If a customer's email matches an existing account in your system, they may be matched automatically though a one-time sign-in step on your side may still be required in some cases.
3. Reduces drop-off during the linking flow for new customers.

Set up account linking

Complete the following steps after you finish the Create an MCP Add-on setup.

New to OAuth? Setting up your authorization server

If you're new to account linking or don't yet have an authorization server, use the guidance below to configure one before continuing.

1. Enable PKCE S256: This is the most common missing step. Without it, alexa-ai deploy will fail.
2. Enable Refresh Token Issuance: Without refresh tokens, customers must re-link their account every time the access token expires.

3. Create an OAuth Application (Client ID): Create a new application in your auth service. This generates a client ID and client secret (optional) that you'll provide to Alexa in Step 3.

   Important: Keep the client secret secure — you'll enter it via a masked prompt in the CLI. Never store it in a file or pass it as a plain text flag.

4. Register Alexa's Redirect URIs: After running alexa-ai configure-account-linking in Step 3, the CLI displays Alexa's redirect URIs. Add all of them to your application's allowed redirect URI list before testing.

   Note: Alexa uses multiple redirect URIs — register all of them. Registering only one will cause linking to fail for customers whose devices are registered in a different region. See Step 4 for full details.

Pre-flight checklist

Run through this checklist before continuing. If any item is unchecked, resolve it first — skipping these causes failures at deploy time.

• Authorization server is live and reachable over HTTPS
• PKCE S256 is enabled (code_challenge_methods_supported includes S256)
• Refresh tokens are issued alongside every access token
• Client ID and secret are created and noted securely
• MCP server is deployed and publicly accessible

Step 1 — Prepare your MCP server

Your MCP server must be deployed and publicly accessible before you begin. Your MCP server must do two things to support account linking.

1a — Host a well-known metadata document

Alexa reads this document automatically when you configure account linking. It tells Alexa which authorization server to use and what scopes your service supports. You never need to enter auth server URLs manually — Alexa discovers them from this document.

Host the following JSON document at this exact path on your MCP server:

https://your-mcp-server.com/.well-known/oauth-protected-resource

{
  "resource": "https://your-mcp-server.com/mcp",
  "authorization_servers": [
    "https://auth.yourserver.com"
  ],
  "scopes_supported": [
    "openid",
    "your-custom-scope"
  ]
}

1b — Return HTTP 401 or 403 when a tool is called without a valid token

When a customer invokes a tool that requires authentication before they've linked their account, your MCP server must return a 401 or 403 response. Alexa detects this and automatically initiates the account linking flow. You don't need to build any linking UI — just return the error status.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Access token required to use this tool."
}

Step 2 — Run alexa-ai new

When you run alexa-ai new to create your add-on, the setup includes the question "Does your Add-on require account linking? (Y/N)".

• N — No account linking configured. You can add it later by running alexa-ai configure-account-linking --addon-id <id> at any point before certification.
• Y — Your manifest is updated with accountLinking.enabled: true. No credentials are collected at this step. The CLI reminds you to run alexa-ai configure-account-linking when your auth server is ready.

Step 3 — Configure account linking

Run the configure-account-linking command when your authorization server is deployed and your well-known metadata document is accessible.

alexa-ai configure-account-linking \
  --addon-id <your-addon-id> \
  --stage development \
  --client-id your-client-id

# Your client secret is entered via a secure masked prompt.
# Alternatively, set the ALEXA_CLIENT_SECRET environment variable.
# Never pass --client-secret as a plain text flag.

Alexa reads your well-known metadata document and automatically discovers your authorization endpoint, token endpoint, supported scopes, token scheme, and token expiry. It also validates that your authorization server supports PKCE S256 — deployment is blocked if S256 isn't found. After the command runs, the CLI prints a discovery summary. Review it to confirm the endpoints and scopes are correct before proceeding.

Step 4 — Register Alexa's redirect URIs

Alexa uses multiple redirect URIs — the exact URI used at runtime depends on where the customer registered their Alexa device. This is a common integration mistake that causes OAuth redirects to fail for a subset of customers.

The correct approach:

1. In the Alexa+ Developer Hub, find the list of Alexa redirect URIs for your add-on and register all of them on your authorization server as allowed redirect URIs.
2. At runtime, your authorization server receives a redirect_uri parameter in the authorization request from Alexa. Use exactly the value Alexa passes — don't hardcode a single URI.
3. Before redirecting the customer back, verify the received redirect_uri is in your registered list. If it isn't, return an error.

Step 5 — Deploy

alexa-ai deploy

Alexa validates your account linking configuration automatically and shows a confirmation summary. Review the summary and confirm to complete deployment. Use --yes to skip the confirmation prompt in CI/CD pipelines.

Related topics

• Overview
• Create an MCP Add-on
• Alexa+ MCP Design Guide
• Authentication

Last updated: Jul 10, 2026