OCAPI Session Bridge

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 reauthenticate 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.

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. If successful, you get the JWT back as Authorization:Bearer response header.

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

REQUEST:
POST /dw/shop/v24_5/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" : "24.5",
   "_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/v24_5/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’s 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.

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. If successful, 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 approach 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/v24_5/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 a dwsecuretoken.

REQUEST:
POST /dw/shop/v24_5/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’s 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.