Exchanges a grant for an OAuth access token. Supported `grant_type` values:
| grant_type | Flow | Required (besides grant_type) |
|----------------------|------------------|---------------------------------|
| `client_credentials` | seller-direct | client auth (see below) |
| `authorization_code` | delegated | `code`, `code_verifier` (PKCE) |
| `refresh_token` | delegated | `refresh_token` |
**Client authentication:** credentials in the form body (`client_secret_post`)
— `client_id` + `client_secret`. HTTP Basic is also accepted. **Public
clients** (Solution-Provider apps registered `token_endpoint_auth_method: none`)
send no secret on the delegated grants; PKCE protects the code.
**`client_credentials`:** issues **no** refresh token (re-mint on expiry).
**`scope` is decorative here** — accepted for compatibility but **not honored**;
access is governed by the scopes provisioned per client in IAM (ADR-012); there
is no down-scoping and the response does not echo `scope`. (Verified: `/v3/token`
ignores any `scope=` value.)
**`authorization_code`:** `redirect_uri` is accepted for OAuth 2.0 back-compat
but not required in 2.1 (PKCE covers injection).
**`refresh_token`:** the response includes a **rotated** `refresh_token` — the
presented token is invalidated (OAuth 2.1 §4.3.1; IAM rotates today, ~1-year
TTL). A requested `scope` MUST NOT exceed the originally granted scope.
**Token:** `Bearer` (RFC 6750), sent downstream as `Authorization: Bearer
<token>` — **not** `WM_SEC.ACCESS_TOKEN`.
**Implemented by `authorization-service` as a stateless proxy to Walmart IAM (ADR-026).**
Request
This endpoint expects an object.
grant_typeenumRequired
The OAuth grant type.
client_idstringOptional
Client identifier (client_secret_post / public clients). Omit if using HTTP Basic.
client_secretstringOptional
Client secret (client_secret_post). Omit for public clients or HTTP Basic.
codestringOptional
Authorization code from /auth/v4/authorize (authorization_code grant).
code_verifierstringOptionalformat: "^[A-Za-z0-9-._~]+$"43-128 characters
PKCE verifier whose S256 hash equals the earlier code_challenge (authorization_code grant).
refresh_tokenstringOptional
A previously issued refresh token (refresh_token grant). Rotated on use.
redirect_uristringOptionalformat: "uri"
Accepted for OAuth 2.0 back-compat on authorization_code; not required in 2.1 (PKCE covers injection).
scopestringOptional
client_credentials: accepted for compatibility but not honored
(ADR-012) — no down-scoping; not echoed. refresh_token: optional;
MUST NOT exceed the originally granted scope.
Response
Access token issued.
access_tokenstring
Opaque Bearer access token. Treat as a secret; never log.
token_typeenum
Always Bearer (RFC 6750).
expires_ininteger
Access-token lifetime in seconds (≈900 today).
refresh_tokenstringOptional
Rotated refresh token — replaces the one presented (OAuth 2.1 §4.3.1).
Present only on delegated grants when offline_access was granted.
Treat as a secret; never log.
scopestringOptional
Space-delimited granted scopes; present on delegated grants when narrowed from the original grant.