Customer Sessions API

Content

Customer sessions collection:

[POST] create session (sing-in)
[POST] refresh session
[GET] index, list active customer sessions

Single customer session:

[DELETE] delete session (sign-out)

General notes

Customer sessions are used for authenticating shop customers. Customer can have multiple active sessions at the time, for each session there is JWT held by client.

After creating new session using credentials, customer receives a pair of unique access and refresh JWT. These JWT cannot be obtained in any another way (except refreshing session).

Hashing algorithm for JWTs is sha256.

Customer sessions collection

Create customer session

POST /api/auth/customer-sessions

Method for creating new CustomerSession, aka signing-in. When successful, fresh CustomerSession with JWT is returned.

Request

Param	Type	Description	Requirements
`email`	string	Customer login email	Required.
`password`	string	Customer password	Required.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json

{
   "email": "john.doe@example.com",
   "password": "secret"
}

Responses

201 CREATED

New CustomerSession was successfully created.

When authenticated customer creates new session, already existing session for provided access token is returned instead.

The access token is written in the response as cookie customer_access_token for authentication on theme.
The refresh token is written in the response as cookie customer_refresh_token for authentication on theme.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 201

{
    "id": 90,
    "customer_id": 1,
    "client_ip": "172.19.0.1",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
    "access_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzcsInN1YiI6OTAsImV4cCI6MTU5MDk0MTczNCwidHlwIjoidSJ9.08a11c387ed0cb82bc2cd289a2fe3ac8663d7b01ca16952c8dd42598de8ce6b6",
    "refresh_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzgsInN1YiI6OTAsImV4cCI6MTU5MjE0NzczNCwidHlwIjoidSJ9.28a43fd4d578a94b7910e1418815472424a9269028c92d5b50732f4305a7f038",
    "access_expiration_at": "2020-05-31T16:15:34+0000",
    "session_expiration_at": "2020-06-14T15:15:34+0000",
    "_links": [
        {
            "href": "/api/auth/customer-sessions/90",
            "rel": "signout",
            "type": "DELETE"
        }
    ]
}

401 UNAUTHORIZED

Invalid credentials.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 401

{
    "type": "Unauthenticated",
    "message": "These credentials do not match our records.",
    "id": "65ae301f-a8e5-4c1e-86d3-48c270e74b63"
}

403 FORBIDDEN

Customer is inactive.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 403

{
    "type": "Forbidden",
    "message": "This account is deactivated.",
    "id": "0c1e31a5-e293-46d1-9288-9c341bde9c53"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "dd311fdc-bc33-49d7-8599-a82cfe68b296",
    "errors": [
        {
            "field": "password",
            "message": "The password field is required."
        }
    ]
}

423 LOCKED

Too many login attempts in time limit. Each 5 unsuccessful login attempts will raise lock time to double, starting at 1 minute.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 423
Retry-After: 60

{
    "type": "Locked",
    "message": "Too many login attempts.",
    "id": "906197cd-8dbe-4d89-8f2a-6548598dc4dc"
}

Refresh customer session

POST /api/auth/customer-tokens

Method for refreshing CustomerSession. When successful, CustomerSession with new valid JWT is returned. All previously active tokens for given session are invalidated. Each refresh token can be used only once before invalidation.

Request

Param	Type	Description	Requirements
`refresh_token`	string	Refresh token.	Required.

POST /api/auth/customer-tokens HTTP/1.1
Content-Type: application/json

{
   "refresh_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5NDMzMTQsImp0aSI6NDAsInN1YiI6OTEsImV4cCI6MTU5MjE1MjkxNCwidHlwIjoidSJ9.bea36238cbab3b117d19464d0ff807c17b9a2ff2711cc52075cf9580bd762be7"
}

Responses

200 OK

CustomerSession was successfully refreshed.

The access token is written in the response as cookie customer_access_token for authentication on theme.
The refresh token is written in the response as cookie customer_refresh_token for authentication on theme.

The session is automatically refreshed on theme when refresh token is present as cookie. You should always check current cookies.

POST /api/auth/customer-tokens HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": 90,
    "customer_id": 1,
    "client_ip": "172.19.0.1",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
    "access_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzcsInN1YiI6OTAsImV4cCI6MTU5MDk0MTczNCwidHlwIjoidSJ9.08a11c387ed0cb82bc2cd289a2fe3ac8663d7b01ca16952c8dd42598de8ce6b6",
    "refresh_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzgsInN1YiI6OTAsImV4cCI6MTU5MjE0NzczNCwidHlwIjoidSJ9.28a43fd4d578a94b7910e1418815472424a9269028c92d5b50732f4305a7f038",
    "access_expiration_at": "2020-05-31T16:15:34+0000",
    "session_expiration_at": "2020-06-14T15:15:34+0000",
    "_links": [
        {
            "href": "/api/auth/customer-sessions/90",
            "rel": "signout",
            "type": "DELETE"
        }
    ]
}

401 UNAUTHORIZED

Invalid refresh token.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 401

{
    "type": "Unauthenticated",
    "message": "These credentials do not match our records.",
    "id": "65ae301f-a8e5-4c1e-86d3-48c270e74b63"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "dd311fdc-bc33-49d7-8599-a82cfe68b296",
    "errors": [
        {
            "field": "refresh_token",
            "message": "The refresh_token field is required."
        }
    ]
}

Customer sessions index

GET /api/auth/customer-sessions

This method requires authentication.

Get list of existing CustomerSessions for authenticated customer.

Request

Index behaviour	Definition
Paginated by default	No
Sorting	-
Filters	-
Embedded	-

GET /api/auth/customer-sessions HTTP/1.1

Responses

200 OK

GET /api/auth/customer-sessions HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "items": [
        {
            "id": 90,
            "customer_id": 1,
            "client_ip": "172.19.0.1",
            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
            "access_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzcsInN1YiI6OTAsImV4cCI6MTU5MDk0MTczNCwidHlwIjoidSJ9.08a11c387ed0cb82bc2cd289a2fe3ac8663d7b01ca16952c8dd42598de8ce6b6",
            "refresh_token": "eyJhbGciOiJzaGEyNTYiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1OTA5MzgxMzQsImp0aSI6MzgsInN1YiI6OTAsImV4cCI6MTU5MjE0NzczNCwidHlwIjoidSJ9.28a43fd4d578a94b7910e1418815472424a9269028c92d5b50732f4305a7f038",
            "access_expiration_at": "2020-05-31T16:15:34+0000",
            "session_expiration_at": "2020-06-14T15:15:34+0000",
            "_links": [
                {
                    "href": "/api/auth/customer-sessions/90",
                    "rel": "signout",
                    "type": "DELETE"
                }
            ]
        }
    ]
}

Single customer session

Delete customer session

DELETE /api/auth/customer-sessions/{session_id}

This method requires authentication.

Method for deleting CustomerSession. When session is deleted, JWT for this session will be deactivated.

Request

DELETE /api/auth/customer-sessions/1 HTTP/1.1

Responses

204 NO CONTENT

CustomerSession successfully deleted.

The access token written in cookie customer_access_token is also deleted. The refresh token written in cookie customer_refresh_token is also deleted.

DELETE /api/auth/customer-sessions/1 HTTP/1.1
Status-Code: 204

404 NOT FOUND

CustomerSession was not found.

DELETE /api/auth/customer-sessions/1 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Specified session was not found.",
    "id": "0f54de4d-82d9-4234-9d6b-c8b59233e8e1"
}

Content​

General notes

Customer sessions collection

Create customer session​

POST /api/auth/customer-sessions

Request​

Responses​

201 CREATED​

401 UNAUTHORIZED​

403 FORBIDDEN​

422 UNPROCESSABLE ENTITY​

423 LOCKED​

Refresh customer session​

POST /api/auth/customer-tokens

Request​

Responses​

200 OK​

401 UNAUTHORIZED​

422 UNPROCESSABLE ENTITY​

Customer sessions index​

GET /api/auth/customer-sessions

Request​

Responses​

200 OK​

Single customer session

Delete customer session​

DELETE /api/auth/customer-sessions/{session_id}

Request​

Responses​

204 NO CONTENT​

404 NOT FOUND​

Content

Create customer session

Request

Responses

201 CREATED

401 UNAUTHORIZED

403 FORBIDDEN

422 UNPROCESSABLE ENTITY

423 LOCKED

Refresh customer session

Request

Responses

200 OK

401 UNAUTHORIZED

422 UNPROCESSABLE ENTITY

Customer sessions index

Request

Responses

200 OK

Delete customer session

Request

Responses

204 NO CONTENT

404 NOT FOUND