OCAPI session bridge 20.9

To allow seamless interaction between OCAPI and your session-based storefront we offer the OCAPI session bridge. It allows you to obtain a JWT for a session and vice versa without having to re-authenticate the customer.

Technically the bridge consists of two resources:

  1. Request a JWT for a session via /customers/auth resource.

  2. Request a session for a JWT via /sessions resource.

Obtain JWT

To obtain a JWT for a guest or registered customer you have to pass a valid dwsid cookie to /customers/auth resource. You have to use "type":"session". If you haven't enabled the global security preference Enforce HTTPS, you must also pass a valid dwsecuretoken in the request. In case of success, you get the JWT back as Authorization:Bearer response header.

The following sample shows how this works when the global security preference Enforce HTTPS isn't enabled and the dwsecuretoken is included in the request.

REQUEST:
POST /dw/shop/v20_9/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==;

{
  "type" : "session"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8

{
   "_v" : "20.9",
   "_type" : "customer",
   "auth_type" : "guest",
   "customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
   "preferred_locale" : "default"
}

When the global security preference Enforce HTTPS is enabled, the request would be similar to this example, which doesn't include a dwsecuretoken:

REQUEST:
POST /dw/shop/v20_9/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==

{
  "type" : "session"
}

Note: There is no tight coupling between session and JWT. You get different tokens for multiple requests with the same session. Therefore, you should make only one call per session.

For more details see /customers/auth resource.

Obtain Session

To obtain a session for a guest or registered customer you have to pass a valid JWT to /sessions resource. The JWT has to be passed as Authorization:Bearer request header. In case of success you get the session cookies back.

If you haven't enabled the global security preference Enforce HTTPS, the response includes a Set-Cookie header for a dwsecuretoken. The Set-Cookie header for a dwsecuretoken isn't included in the response if the global security preference Enforce HTTPS is enabled.

The following sample shows how this works when the global security preference Enforce HTTPS isn't enabled and the dwsecuretoken is included as a Set-Cookie header in the response.

REQUEST:
POST /dw/shop/v20_9/sessions HTTP/1.1
Host: example.com
x-dw-client-id: [your_own_client_id]
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX

RESPONSE:
HTTP/1.1 204 NO CONTENT
Set-Cookie : dwsecuretoken_a85a5236a2e852d714eb6f1585efb61c=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT;
Set-Cookie : dwsid=eXv5R3FZGI4BBfbK1Opk5s1mJ-41Aw7ZuaMKxeye5xa16fJMX--AnNkXsvmakbi1UZSzP1zoPmUILgoom1_jKg==;
Set-Cookie : dwanonymous_a85a5236a2e852d714eb6f1585efb61c=bdjalnzmfrkJ0FtYliwud5db67; Max-Age=15552000;
Cache-Control: max-age=0,no-cache,no-store,must-revalidate

When the global security preference Enforce HTTPS is enabled, the response would be similar to this example, which doesn't include a Set-Cookie header for adwsecuretoken.

REQUEST:
POST /dw/shop/v20_9/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==

{
  "type" : "session"
}

Note: There is no tight coupling between session and JWT. You get different sessions for multiple requests with the same JWT. Means, you should make only one call per JWT.

For more details see /sessions resource.

OCAPI obsolete versions 13.x and 14.x will be end of life in 2020 and versions 15.x and 16.x in 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.