Skip to navigation

Issue an access token (client_credentials, authorization_code, or refresh_token)

Exchanges a grant for an OAuth access token. Supported grant_type values:

grant_typeFlowRequired (besides grant_type)
client_credentialsseller-directclient auth (see below)
authorization_codedelegatedcode, code_verifier (PKCE)
refresh_tokendelegatedrefresh_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).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
grant_typeenumRequired
The OAuth grant type.
Allowed values:
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).

Allowed values:
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.

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error
500
Internal Server Error