The OIDC IDP Login endpoints handle the initiation of OpenID Connect authentication flows. When a user needs to authenticate via OIDC, they are redirected to these endpoints which then redirect them to the configured OIDC provider for authentication.
openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses OIDC Authentication API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
tags:
- name: OIDC Authentication
description: 'The OIDC IDP Login endpoints handle the initiation of OpenID Connect authentication flows.
When a user needs to authenticate via OIDC, they are redirected to these endpoints which then redirect them to the configured OIDC provider for authentication.
'
paths:
/oidc-idp/login/stores/{storeId}/authentication-realms/{realmId}:
get:
tags:
- OIDC Authentication
summary: Initiate OIDC Login
description: 'Initiate the OIDC login flow for a specific store and authentication realm
::: note This is not an **API Endpoint**, but the [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of the OpenID Connect Authentication Flow.
To initiate an OpenID Connect authentication you must change the location in the Browser to this URL, not call it asynchronously. :::'
operationId: get-oidc-idp-login-stores-storeId-authentication-realms-realmId
parameters:
- name: storeId
in: path
description: The ID of the store.
required: true
schema:
type: string
format: uuid
- name: realmId
in: path
description: The ID of the authentication realm.
required: true
schema:
type: string
format: uuid
- name: client_id
in: query
description: The Client ID, for Account Management Authentication see the `meta.client_id` field on [Account Authentication Settings](/docs/api/accounts/get-v-2-settings-account-authentication).
required: true
schema:
type: string
- name: redirect_uri
in: query
description: Redirection URI to which the response will be sent. Must exactly match a pre-registered redirect URI for the client in the `redirect_uris` of the [Authentication Realm](/docs/api/single-sign-on/get-v-2-authentication-realms-realm-id).
required: true
schema:
type: string
format: uri
- name: response_type
in: query
description: OIDC/OAuth 2.0 response type, this must be "code" in Commerce.
required: true
schema:
type: string
const: code
- name: scope
in: query
description: Space-delimited list of scopes. Must include "openid", "email", and "name".
required: true
schema:
type: string
- name: state
in: query
description: Opaque value used to maintain state between the request and the callback. Helps prevent CSRF.
required: true
schema:
type: string
maxLength: 2048
- name: code_challenge_method
in: query
description: '[Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) transformation method that was used to derive code_challenge.'
required: true
schema:
type: string
enum:
- S256
- plain
example: S256
- name: code_challenge
in: query
description: '[Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) Code Challenge.'
required: true
schema:
type: string
- name: prompt
in: query
description: Space-delimited, case-sensitive list that specifies whether the Authorization Server prompts the End-User for re-authentication and consent. This value is passed to the configured IdP. See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
required: false
schema:
type: string
- name: display
in: query
description: ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface. This value is passed to the configured IdP. See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
required: false
schema:
type: string
- name: ui_locales
in: query
description: End-User's preferred languages and scripts for the user interface, represented as space-separated list of BCP47 language tag values. This value is forwarded to the configured IdP. See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
required: false
schema:
type: string
example: fr-CA fr en
- name: elasticpath_commerce_cloud_profile_id
in: query
description: Selects the specific OIDC Profile within the realm to use for authentication.
required: true
schema:
type: string
format: uuid
- name: ep_report_callback_replay_error
in: query
description: Custom boolean flag. If true, if the user attempts to hit back in their browser, we will redirect them back to the store front
required: false
schema:
type: boolean
responses:
'303':
description: See Other - Redirects to the IdP provider for authentication
headers:
Location:
description: The URL of the IdP provider to redirect to
schema:
type: string
format: uri
'307':
description: Temporary Redirect - Redirects the user back to the caller.
headers:
Location:
description: The location to redirect to, typically the store front.
schema:
type: string
format: uri
'400':
description: 'In some cases the OAuth 2.0 specification does not permit us to redirect the user back to the caller, in which case they will see a 4xx.
'
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: OAuth 2.0 error code
errorDescription:
type: string
description: Human-readable error description (camelCase)
error_description:
type: string
description: Human-readable error description (snake_case, OAuth 2.0 standard)
required:
- error
examples:
invalid_client:
summary: Invalid client_id
value:
error: invalid_request
errorDescription: The field [client_id] with value [unknownClient] is invalid.
error_description: The field [client_id] with value [unknownClient] is invalid.
security: []
/oidc-idp/stores/{storeId}/authentication-realms/{realmId}/.well-known/openid-configuration:
get:
tags:
- OIDC Authentication
summary: OpenID Connect Discovery
description: 'Returns the OpenID Connect discovery document for the authentication realm.
This endpoint provides metadata about the OIDC provider''s configuration, including endpoints, supported features, and capabilities. Some libraries might require an OIDC discovery document in order to work.
For more information see [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)'
operationId: get-oidc-idp-stores-storeId-authentication-realms-realmId-well-known-openid-configuration
parameters:
- name: storeId
in: path
description: The ID of the store.
required: true
schema:
type: string
format: uuid
- name: realmId
in: path
description: The ID of the authentication realm.
required: true
schema:
type: string
format: uuid
- name: elasticpath_commerce_cloud_profile_id
in: query
description: The ID of the [OIDC profile](/docs/api/single-sign-on/oidc-profiles) that you would like to authenticate with
required: false
schema:
type: string
format: uuid
responses:
'200':
description: OK - OpenID Connect discovery document
content:
application/json:
schema:
type: object
properties:
issuer:
type: string
format: uri
description: The issuer identifier for this OIDC provider
authorization_endpoint:
type: string
format: uri
description: URL of the authorization endpoint
token_endpoint:
type: string
format: uri
description: URL of the token endpoint, note that this endpoint is not public, and clients will not call it.
jwks_uri:
type: string
format: uri
description: URL of the JSON Web Key Set document
response_types_supported:
type: array
items:
type: string
description: List of OAuth 2.0 response_type values supported
subject_types_supported:
type: array
items:
type: string
description: List of subject identifier types supported
id_token_signing_alg_values_supported:
type: array
items:
type: string
description: List of JWS signing algorithms supported for ID Tokens
scopes_supported:
type: array
items:
type: string
description: List of OAuth 2.0 scope values supported
token_endpoint_auth_methods_supported:
type: string
description: Authentication methods supported by the token endpoint
required:
- issuer
- authorization_endpoint
- token_endpoint
- jwks_uri
- response_types_supported
- subject_types_supported
- id_token_signing_alg_values_supported
examples:
discovery_document:
summary: OpenID Connect discovery document
value:
authorization_endpoint: http://euwest.api.elasticpath.com/oidc-idp/login/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af
id_token_signing_alg_values_supported:
- RS256
issuer: http://euwest.api.elasticpath.com/oidc-idp/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af
jwks_uri: http://euwest.api.elasticpath.com/oidc-idp/.well-known/jwks.json
response_types_supported:
- code
scopes_supported:
- profile
- openid
- email
subject_types_supported:
- public
token_endpoint: http://euwest.api.elasticpath.com/oidc-idp/token/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af
token_endpoint_auth_methods_supported: client_secret_basic
security: []
components:
securitySchemes:
BearerToken:
type: http
scheme: bearer