User Sessions API

Content

User sessions collection:

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

Single user session:

• [DELETE] delete session (sign-out)

General notes

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

After creating new session using credentials, user 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.

User sessions collection

Create user session

POST /api/auth/user-sessions

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

Request

Param	Type	Description	Requirements
email	string	User login email	Required.
password	string	User password	Required.

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

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

Responses

201 CREATED

New UserSession was successfully created.

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

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

{
    "id": 90,
    "user_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",
    "two_factor_verified": true,
    "_links": [
        {
            "href": "/api/auth/user-sessions/90",
            "rel": "signout",
            "type": "DELETE"
        }
    ]
}

401 UNAUTHORIZED

Invalid credentials.

POST /api/auth/user-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

User is inactive.

POST /api/auth/user-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/user-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/user-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 user session

POST /api/auth/user-tokens

Method for refreshing UserSession. When successful, UserSession 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/user-tokens HTTP/1.1
Content-Type: application/json

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

Responses

200 OK

UserSession was successfully refreshed.

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

{
    "id": 90,
    "user_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/user-sessions/90",
            "rel": "signout",
            "type": "DELETE"
        }
    ]
}

401 UNAUTHORIZED

Invalid refresh token.

POST /api/auth/user-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/user-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."
        }
    ]
}

---

User sessions index

GET /api/auth/user-sessions

This method requires authentication.

Get list of existing UserSessions for authenticated user.

Request

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

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

Responses

200 OK

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

{
    "items": [
        {
            "id": 90,
            "user_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",
            "two_factor_verified": true,
            "_links": [
                {
                    "href": "/api/auth/user-sessions/90",
                    "rel": "signout",
                    "type": "DELETE"
                }
            ]
        }
    ]
}

---

---

Single user session

Delete user session

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

This method requires authentication.

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

Request

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

Responses

204 NO CONTENT

UserSession successfully deleted.

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

404 NOT FOUND

UserSession was not found.

DELETE /api/auth/user-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"
}