Authentication

Pelcro uses JSON Web Token (JWT), an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted as it is digitally signed.

Once the user has registered or has logged in, each subsequent request to protected endpoints requires the JWT token containing the identity of the customer to be provided in the Authorization header, prefixed with the Bearer token.

This implementation makes it easy to implement Single Sign-On across different domains and properties.

Authorization header

Protected endpoints on Open API require the JWT token containing the identity of the customer to be provided in the Authorization header, prefixed with the Bearer token. Here's a sample of a properly formatted request containing the necessary Authorization header including the JWT token.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3BlbGNyby1mdHJ1ZGVhdS5uZ3Jvay5pby9hcGkvdjEvc2RrL2N1c3RvbWVyIiwiaWF0IjoxNjk3MjMxNjUyLCJleHAiOjE3MDI0MTU2NTIsIm5iZiI6MTY5NzIzMTY1MiwianRpIjoiVnY2MkVHdlJtUHVjaUd1VCIsInN1YiI6IjIwNyIsInBydiI6IjIzYmQ1Yzg5NDlmNjAwYWRiMzllNzAxYzQwMDg3MmRiN2E1OTc2ZjcifQ.D5yr8e5o_QqnntWaMopBSYEV6vWf6eRdt3L9oorEDAA
User-Agent: PostmanRuntime/7.33.0
Accept: application/json
Cache-Control: no-cache
Host: www.pelcro.com
Accept-Encoding: gzip, deflate, br

Token lifetime

The length of time the token will be valid for is 60 days by default. If you want to extend the lifetime of the session for the authenticated customer, you can request a new token via the refresh endpoint.

Handling invalid or expired tokens

If the provided token is invalid or has expired, a 401 Unauthorized status code will be returned. If this occurs, customer needs to login again in order to receive a fresh token to be used for all subsequent requests performed on protected endpoints.

{  
    "error": {  
        "status": 401,
        "message": "Invalid or expired token"
    }  
}

Handling blacklisted tokens

If the provided token has been blacklisted, a 403 Forbidden status code will be returned. This can occur in relationship with the Single user authentication feature, which prevents concurrent logins.

If this error is returned, customer needs to login again in order to receive a fresh token to be used for all subsequent requests performed on protected endpoints.

{  
    "error": {  
        "status": 403,
        "message": "Authentication token has been blacklisted, please try again"
    }  
}