Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Authentication Workflow

Authentication Workflow

This section describes the out-of-the-box authentication workflow. The diagram below illustrates the workflow and each subsection describes one of the workflow steps in greater detail.


1)The client sends a POST request to the OAuth2 endpoint with the following:

Field Usage
grant_type The OAuth2 grant type. Cortex OAuth2 currently only supports the 'password' grant type.
username The end-user's username. This field is optional and is only required if the role requested is REGISTERED
password The end-user's password. This field is optional and is only required if the role requested is REGISTERED
scope The requested scope.
role The requested role.

A request will be as follows:

Content-Type: application/x-www-form-urlencoded


Cortex's OAuth2 implementation only accepts requests of content-type application/x-www-urlencoded-form, as specified by the Oauth2 specifications.

2) OAuth2 Endpoint Sends POST Request to Authentication Endpoint

The OAuth2 Endpoint creates a POST request with the customer's authentication details (username, password, scopes and roles) in a JSON body. A trust header is attached to the request to ensure the call is from a legitimate OAuth2 Endpoint. The request is then sent to the Authentication Endpoint.

Content-Type: application/json
x-ep-trust-header: <secret trust header>

The Authentication Endpoint receives the user credentials from the POST request and authenticates the user. Once authenticated, the user's user identifier, scopes, and roles are returned in the following response to the OAuth2 Endpoint.

Date: Fri, 09 May 2013 16:01:30 GMT
Content-Length: 81
Content-Type: application/json
Cache-Control: no-store
   "x-ep-user-id": "67E280AC-7E86-32A3-59B2-610FF2CA38DD",
   "x-ep-user-roles": "REGISTERED",
   "x-ep-user-scopes": "MOBEE"

4) OAuth2 Endpoint Generates an Access Token

The Authentication Endpoint generates an OAuth2 access token and maps the customer's user ID, scope, and role to the token in the database. The access token is then returned to the client in the following JSON object.

   "access_token": "c7326d79-9273-4820-b45d-587f90d1dc9b",
   "expires_in": 359,
   "scope" : "MOBEE",
   "role": "REGISTERED"

5) Client Makes Request to Cortex Resource with Access Token

A Client puts the access token in an Authorization header and makes a request for a resource. The OAuth2 endpoint receives the request, extracts the access token from the request header, and retrieves the corresponding user values. The user's values are populated into the following authentication headers:

Header Description
x-ep-user-id The authenticated user's user identifier.
x-ep-user-roles The requested roles.
x-ep-user-scopes The requested scopes.

The headers are attached to a request that is sent to the resource. Below is an example of this flow:


6) Request with Authentication Headers sent to Cortex

Cortex takes the authentication header values and creates a subject for authorization. If the user is authorized to retrieve a resource, the operation continues. Otherwise, a access to the resource is denied, and a 401 response is returned to the client.