Authentication

How to use JWT to authenticate with our RESTful API

To authenticate a request, a client application must send a JSON Web Token (JWT) in the authorization header of the HTTP request to our back-end RESTful API.

Bloqifi RESTful API validates a JWT in a performant way by using the JWT issuer's JSON Web Key Set (JWKS).

Although this example is somewhat basic, it should provide a clear idea of our logic with JWT. As stated above, any interaction with our secure RESTful API would start with a login request, which would look something like the following:

Generate JSON Web Token (JWT)

POST https://api.bloqifi.com/v0/token

Request Body

Name	Type	Description
email*	String	[a-z0-9._%+-]+@[a-z0-9.-]+.[a-z]{2,4}$
password*	String	(?=.\d)(?=.[a-z])(?=.*[A-Z]).{6,}

200: OK Welcome back..

{
    accessToken: token, // 30 minutes expiry
    refreshToken: token // 1 day expiry
}

401: Unauthorized Incorrect email or password or both

{
    message: 'Authentication failed. Invalid user or password.'
}

202: Accepted Pending email confirmation

{
    message: 'Authentication failed. Email not verified.'
}

201: Created Pending user confirmation

{
    message: 'Authentication failed. Identity not verified.'
}

404: Not Found Incorrect email or password or both

{
    message: 'Authentication failed.'
}

curl

curl -X POST https://api.bloqifi.com/v0/token \
-H "Content-Type: application/json" \
-d '{"email":"my_email","password":"my_password"}'

The payload is as follows:

{
    'email': 'my_email'
    'password': 'my_password'
}

Assuming the credentials are valid, the system would return a new JSON Web Token. (Access & Refresh) Let’s go over the details of this token. Particularly, let’s think about the information inside our payload. Some interesting options could be:

• Email: Contains the email of the logged in user, which is especially useful since we might want to show that in our UI

• Exp: We’ll only allow our new token to be used for the next fifteen minutes, which is about how long users should need it on a daily basis, before requesting a new access token based on their refresh token.

• Status: Contains the status of the logged in user, which is useful since we might need to verify this account.

To keep things simple, we’ll use an HS256 algorithm for encoding the data.

Let’s consider what the different sections of our token should look like:

Header: with the type (JWT) and type of coding.

{
    alg: 'HS256',
    typ: 'JWT'
}

Payload: It is where the user’s information will be found that will allow the server to discern whether or not it can access the requested resource.

{
    email: '[email protected]',
    firstName: 'First Name',
    lastName: 'Family Name',
    exp: 1550946689,
    iat: 1550946689,
    role: {
        name: 'Tier 1',
        permissions: Array[{}]
    }
    permissions: Array[{}],
    status: 200
}

Any further requests sent by the client app will contain this same access token. In turn, the token will be validated by the server, and the result compared with the signature portion of the token.

In a typical JWT request, you’ll pass the token as part of the authorization header on the client-side after the client logged in, like Authorization: Bearer.

Doing so would prevent, for example, someone from meddling with the message’s payload and changing the role to Admin, allowing a fake or even a valid non-admin user, to execute a privileged action like issuing a payment to create a bloq.

Types of token

There are many types of token, although in authentication with JWT the most typical are access token and refresh token.

• Access token: It contains the information our server needs to know so the user / device can access the resource their are requesting or not.

• Refresh token: The refresh token is used to generate a new access token.

Refresh access token

The refresh token requires greater security when it is stored than the access token, as if it were stolen by third parties, they could use it to obtain new access tokens and access the protected resources of the application.

Exchange refresh token for access token

PUT https://api.bloqifi.com/v0/token

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Name	Type	Description
token*	String	${refreshToken}

201: Created Access token available

{
    accessToken: token, // 30 minutes expiry
}

401: Unauthorized No payload, only header

Revoke refresh token

Should you need to revoke a refresh token for any reason, this endpoints makes it possible.

Revoke refresh token

DELETE https://api.bloqifi.com/v0/token

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer ${accessToken}

Request Body

Name	Type	Description
token*	String	${refreshToken}

204: No Content Token removed

400: Bad Request Failed

{
    message: 'Failed to revoke token..'
}

Generate refresh token

Enabled user generated refresh token with predefined expiry

Generate refresh token

PATCH https://api.bloqifi.com/v0/token

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer ${accessToken}

Request Body

Name	Type	Description
exp*	Number	Number of seconds
token*	String	${refreshToken}

201: Created New refresh token available

{
    refreshToken: token, // user-defined expiry
}

400: Bad Request Failed

{
    message: 'Failed to generate token..'
}

Good to know: Be careful with this endpoint. Do not generate refresh tokens with unreasonable expiry.

Keep the time limit within use case.

Hint: 1 day is 86400 seconds