Tokens

Tokens Endpoint    /tokens

Routes	Method	Headers	Query String	Body
/tokens/me	GET	Authorization Header	-	-
/tokens/whoami	GET	Authorization Header	-	-
/tokens/generate-token	POST	X-Ertis-Alias, X-IpAddress (optional), X-UserAgent (optional)	-	Username & Password payload
/tokens/verify-token	GET	Authorization Header	-	-
/tokens/verify-token	POST	-	-	Token payload
/tokens/refresh-token	GET	Authorization Header	revoke=true (Default false)	-
/tokens/refresh-token	POST	-	revoke=true (Default false)	Token payload
/tokens/revoke-token	GET	Authorization Header	logout-all=true (Default false)	-
/tokens/revoke-token	POST	-	logout-all=true (Default false)	Token payload

Login / Generate Token

Request Model

curl --location --request POST '{{base_url}}/api/v1/generate-token' \
--header 'X-Ertis-Alias: {{membership_id}}' \
--header 'X-IpAddress: {{client_ip}}' \
--header 'X-UserAgent: {{user_agent}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "{{username}}",
    "password": "{{password}}"
}'

Body Model

{
    "username": "{{username}}",
    "password": "{{password}}"
}

Successful Response

Status Code : 201 Created

{
    "token_type": "bearer",
    "refresh_token": "{refresh_token}",
    "refresh_token_expires_in": 86400,
    "access_token": "{access_token}",
    "expires_in": 43200,
    "created_at": "2021-09-01T20:46:03.1354057+03:00"
}

Failed Response (Username or password incorrect)

Status Code : 401 Unauthorized

{
    "Message": "Username or password is wrong",
    "ErrorCode": "UsernameOrPasswordIsWrong",
    "StatusCode": 401
}

Failed Response (X-Ertis-Alias Header Missing)

Status Code : 400 Bad Request

{
    "message": "Membership id should be added in headers with 'X-Ertis-Alias' key.",
    "errorCode": "XErtisAliasMissing",
    "statusCode": 400
}

---

Me

Request Model

curl --location --request GET '{{base_url}}/api/v1/me' \
--header 'Authorization: Bearer {{access_token}}'

or

curl --location --request GET '{{base_url}}/api/v1/whoami' \
--header 'Authorization: Bearer {{access_token}}'

Successful Response

Status Code : 200 OK

{
    "_id": "{{id}}",
    "firstname": "{{first_name}}",
    "lastname": "{{last_name}}",
    "username": "{{username}}",
    "email_address": "{{email}}",
    "role": "{{role}}",
    "permissions": [],
    "forbidden": [],
    "sys": {
        "created_at": "2021-06-03T20:29:22.545+03:00",
        "created_by": "{{created_by}}",
        "modified_at": "2021-09-01T18:31:57.932+03:00",
        "modified_by": "{{modified_by}}",
    },
    "membership_id": "{{membership_id}}"
}

Failed Response (Authorization Header Missing)

Status Code : 400 Bad Request

{
    "Message": "Authorization header missing or empty",
    "ErrorCode": "AuthorizationHeaderMissing",
    "StatusCode": 400
}

Failed Response (Ambiguous or unsupported token type)

Status Code : 400 Bad Request

{
   "Message": "Token type not supported. Token type must be one of Bearer or Basic",
   "ErrorCode": "TokenTypeNotSupported",
   "StatusCode": 400
}

Failed Response (Invalid token)

Status Code : 401 Unauthorized

{
   "Message": "Provided token is invalid",
   "ErrorCode": "InvalidToken",
   "StatusCode": 401
}

Failed Response (Expired token)

Status Code : 401 Unauthorized

{
   "Message": "Provided token was expired",
   "ErrorCode": "TokenWasExpired",
   "StatusCode": 401
}

Failed Response (Revoked token)

Status Code : 401 Unauthorized

{
   "Message": "Provided token was revoked",
   "ErrorCode": "TokenWasRevoked",
   "StatusCode": 401
}

---

Verify Token

Request Model

curl --location --request GET '{{base_url}}/api/v1/verify-token' \
--header 'Authorization: Bearer {{access_token}}'

or

curl --location --request POST '{{base_url}}/api/v1/verify-token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "Bearer {{access_token}}"
}'

Successful Response

Status Code : 200 OK

{
    "verified": true,
    "token": "{{access_token}}",
    "token_kind": "access_token",
    "remaining_time": {{remaining_time_seconds}}
}

---

Refresh Token

Request Model

curl --location --request GET '{{base_url}}/api/v1/refresh-token' \
--header 'Authorization: Bearer {{refresh_token}}'

or

curl --location --request POST '{{base_url}}/api/v1/refresh-token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "Bearer {{refresh_token}}"
}'

 

If you want to revoke the current token besides the token refresh, add "?revoke=true" to the query string

 

Successful Response

Status Code : 201 Created

{
    "token_type": "bearer",
    "refresh_token": "{refresh_token}",
    "refresh_token_expires_in": 86400,
    "access_token": "{{access_token}}",
    "expires_in": 43200,
    "created_at": "2021-09-01T20:46:03.1354057+03:00"
}

Failed Response (Expired refresh token)

Status Code : 401 Unauthorized

{
    "Message": "Provided refresh token was expired",
    "ErrorCode": "RefreshTokenWasExpired",
    "StatusCode": 401
}

---

Logout / Revoke Token

Request Model

curl --location --request GET '{{base_url}}/api/v1/revoke-token' \
--header 'Authorization: Bearer {{access_token}}'

or

curl --location --request POST '{{base_url}}/api/v1/revoke-token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "Bearer {{access_token}}"
}'

 

If you want to log out of all sessions, add "?logout-all=true" to the query string. This operation will be signed-out of all sessions for the owner of the token on all devices.

 

Successful Response

Status Code : 204 No Content

Failed Response (Invalid or already revoked token)

Status Code : 401 Unauthorized