Authenticating an Admin User

This book describes the means we provide in order to authenticate an admin user.

• Introduction
• Getting Token with username + password
• Getting token with a valid auth token

Introduction

Our application relies on a solution based on JWT tokens for authentication and authorization.

This document explains two different ways users can get their authorization token that will enable them to use our services.

A successful request to our API is comprised of a valid endpoint plus an Authorization header with a valid JWT token as its value.

Successful query example

curl --location --request GET 'https://pwallet.partner-domain.com/api/customers/:customerId' --header 'Authorization: Bearer <the token>'

 

Getting Token with username + password

As in any API, we provide the means to get an access token for our application with a valid Admin User and password combination. Both admin user and password need to be provided for a successful login.

API endpoint to get the token is https://pwallet.partner-domain.com/api/auth/adminUsers/login, and must be called as a POST request with a payload comprised of "adminUserName" and "password" must be provided in order for this to succeed.

cURL example: 

curl --location --request POST 'https://pwallet.partner-domain.com/api/auth/adminUsers/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"adminUserName": "my-admin-user",
"password": "my-password"
}'

A successful response would be an object with a valid "accessToken" value:

{
"accessToken": "the-token"
}

In case of a not valid adminUser or password combination is provided, the response would be:

{
	"success": false,
	"httpStatus": 401,
	"timestamp": "2022-05-21T18:21:14.317Z",
	"error": {
		"code": 401,
		"message": "Unauthorized"
	}
}

Getting token with a valid auth token

Another way of getting a valid JWT token to interact with our services is to use a token we can verify comes from a trustable source.

In order to use this methods, partners will be required to generate a Private / Public RSA key combination and provide us with the public key. This allows us to successfully identify the tokens received as coming from a trustable source.

This token should follow the JWT RS256 format, in which, the payload would include a structure as follows:

{
  sub: // adminUserName,
  rol: // roles,
  aid: // agentId,
  nam: // name,
  oth: // email,
  tit: // title,
}

* The generated tokens log in an admin user if it existed, or creates one with the provided details if none existed.

Required Field description:

• Sub: The admin users name
• Rol: an array of roles to apply (typically, when creating clerks, the payload should be [*clerk]
• Aid: is the masterAgentId, this should be provided by MG

Other fields:

• Nam: Name of the user
• Oth: Email of the user
• Tit: Job title of the user

* These optional fields are descriptive only.

After the token is generated, you can make a POST request to https://pwallet.partner-domain.com/api/auth/adminUsers with a JSON body featuring a "token", property including the value you just generated.

curl --location --request POST 'https://pwallet.partner-domain.com/api/auth/adminUsers/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "your-token"
}'

This is a powerful method, and needs to be used with the knowledge it allows an external agent to log in as any valid user in your platform. Which can prove to be insecure if the private key were provided to bad actors.