> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP identity linking with OAuth 2.0

> UCP identity linking mechanism — OAuth 2.0 Authorization Code flow, authorization server discovery, scope specification, and token revocation (RFC 7009)

# Identity Linking

## 3.1 Capability Identifier

The identity linking namespace is `dev.ucp.common.identity_linking`. It is a cross-domain common capability (`common` rather than `shopping`) because identity linking is not limited to shopping scenarios.

## 3.2 Why Identity Linking Is Needed

Consumers may already have accounts with merchants (membership tiers, loyalty points, saved addresses, order history, payment methods). Identity linking allows AI agents to securely represent consumers and leverage this existing information to deliver a personalized shopping experience — without requiring consumers to re-enter any information or share passwords.

**Checkout without identity linking**: The AI agent can only create a guest checkout. The consumer must manually provide all information.

**Checkout with identity linking**: The AI agent can directly access the consumer's saved addresses, payment methods, and membership benefits, completing the checkout in a single step.

## 3.3 Authorization Server Discovery

UCP requires merchants to publish authorization server metadata at the standard `/.well-known/oauth-authorization-server` endpoint (per RFC 8414):

```json theme={null}
{
  "issuer": "https://store.example.com",
  "authorization_endpoint": "https://store.example.com/oauth/authorize",
  "token_endpoint": "https://store.example.com/oauth/token",
  "revocation_endpoint": "https://store.example.com/oauth/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session",
    "openid",
    "profile"
  ],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}
```

An AI agent can issue a GET request to this endpoint to automatically discover the merchant's OAuth configuration, with no need to hard-code any authorization URLs.

## 3.4 OAuth 2.0 Authorization Code Flow

UCP uses the standard **OAuth 2.0 Authorization Code** flow and mandates PKCE (Proof Key for Code Exchange) for enhanced security:

### Step 1: Generate PKCE Parameters

```text theme={null}
code_verifier = randomly generated 43-128 character string
code_challenge = BASE64URL(SHA256(code_verifier))
```

### Step 2: Initiate Authorization Request

```http theme={null}
GET https://store.example.com/oauth/authorize?
  response_type=code&
  client_id=agent_shopping_001&
  redirect_uri=https://agent.example.com/callback&
  scope=ucp:scopes:checkout_session&
  state=random_csrf_token_xyz&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256
```

**Key parameter descriptions**:

| Parameter               | Description                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `scope`                 | The standard UCP scope is `ucp:scopes:checkout_session`, authorizing the AI agent to manage checkout sessions |
| `state`                 | CSRF protection token; must be an unpredictable random value                                                  |
| `code_challenge`        | PKCE challenge value, preventing authorization code interception attacks                                      |
| `code_challenge_method` | Fixed as `S256` (SHA-256 hash)                                                                                |

### Step 3: User Authorization

The merchant presents an authorization page that clearly informs the user:

* Which AI agent is requesting authorization
* What permissions are being requested
* The user can revoke access at any time

After the user confirms, the merchant redirects the browser to the `redirect_uri` with an authorization code:

```text theme={null}
https://agent.example.com/callback?code=auth_code_abc123&state=random_csrf_token_xyz
```

### Step 4: Token Exchange

```http theme={null}
POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=auth_code_abc123&
redirect_uri=https://agent.example.com/callback&
client_id=agent_shopping_001&
client_secret=secret_xxx&
code_verifier=original_code_verifier_value
```

### Step 5: Receive Tokens

```json theme={null}
{
  "access_token": "at_ucp_xxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_ucp_xxxxxxxxxxxxx",
  "scope": "ucp:scopes:checkout_session"
}
```

## 3.5 UCP Scope Specification

UCP defines standardized scope naming with the `ucp:scopes:` prefix:

| Scope                         | Permitted Operations                             |
| ----------------------------- | ------------------------------------------------ |
| `ucp:scopes:checkout_session` | Create and manage checkout sessions (core scope) |

Merchants may extend with custom scopes beyond UCP's standard scopes. However, AI agents should always follow the **principle of least privilege** — only requesting the scopes they actually need.

## 3.6 Token Revocation (RFC 7009)

UCP requires merchants to implement a token revocation endpoint in compliance with the **RFC 7009 OAuth 2.0 Token Revocation** standard:

```http theme={null}
POST https://store.example.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=at_ucp_xxxxxxxxxxxxx&
token_type_hint=access_token&
client_id=agent_shopping_001&
client_secret=secret_xxx
```

Revocation scenarios include:

* **User-initiated revocation**: The user revokes AI agent authorization in the merchant's account settings
* **Agent-initiated revocation**: The AI agent proactively revokes the token when access is no longer needed
* **Security incident**: Emergency revocation of all tokens upon detecting anomalous activity

When revoking an access\_token, the associated refresh\_token should also be invalidated.

## 3.7 Token Refresh

After an access\_token expires, use the refresh\_token to obtain a new access\_token:

```http theme={null}
POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=rt_ucp_xxxxxxxxxxxxx&
client_id=agent_shopping_001&
client_secret=secret_xxx
```

The response includes a new access\_token and potentially a new refresh\_token (token rotation).

## 3.8 Security Requirements

| Requirement                      | Description                                                                         |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| **PKCE required**                | All Authorization Code flows must use PKCE (S256)                                   |
| **HTTPS required**               | All OAuth endpoints must be served over HTTPS                                       |
| **state parameter**              | Must use unpredictable random values to prevent CSRF                                |
| **Least privilege**              | AI agents should only request scopes they actually need                             |
| **Secure token storage**         | access\_token and refresh\_token must be stored securely; never logged in plaintext |
| **Strict redirect URI matching** | redirect\_uri must exactly match the registered value                               |

***

**Next chapter**: [Order Management](/en/book-3/ch4-orders) — Line item status, fulfillment events, adjustments, and webhook signatures