Skip to content

Authentication and AUthorization

OVES authentication has two sides, the User and the Client. The User is any role used by the internal staff, e.g., Super Admin, OVES Technician, Overall OVES Technician, or Sales. The client is any role that is used by external personnel e.g. distributor, distributor staff, Agent

User

  1. createAuthenticationInstance: Creates a new authentication instance. It returns the ID and name of the created instance.
mutation {
createAuthenticationInstance(
createInstanceInput: { name: "authenticationinstance" }
) {
_id
name
}
}
  1. getAllAuthenticationInstances: Retrieves all authentication instances. It returns the IDs of the instances.
{
getAllAuthenticationInstances(first:100){
page {
edges {
node {
_id
}
}
}
}
}
  1. generateUserRoleSignUpToken: Generates a signup token for a user with a specific email and role. The token is sent to the user's email for signup. The token is sent to the user's email for signup. This mutation will send an authentication token to the email. The token will be used to signup either a super admin, oves technician, overall Oves technician, and sales user. You will pass in the email and the roleId of any user(super admin, Oves technician, overall Oves technician and sales users)
mutation {
generateUserRoleSignUpToken(generateUserRoleSignUpTokenInput:{
email:""
roleId:""
}){
message
status
}
}
  1. signUpUser: Registers a new user with the provided signup credentials, including first name, last name, identification type, ID string, birth date, profile, email, authentication token, and password. It returns an access token and creation timestamp. // This mutation will be used to sign up a user
mutation {
signUpUser(
signUpCredentials: {
firstName: "String!"
lastName: "String!"
idType: PASSPORT
idString: "String!"
birthDate: DateTime
profile: "String!"
email: "String!"
authenticationToken: "String"
password: "String!"
}
) {
accessToken
createdAt
_id
}
}
  1. signInUser: Authenticates a user by email and password. It returns an access token upon successful authentication. //This is the mutation that will be used to sign in a user. After Sign In you will get an accessToken as the response
mutation {
signInUser(signInCredentials:{
email:"String"
password:"String"
}){
accessToken
}
}
  1. checkOvesUserEmailForResetPassword: Checks the user's email for a reset password link and sends it if the email exists. It returns a message and status indicating the success of the operation. This mutation is used to send a reset password link to the user's email
mutation {
checkOvesUserEmailForResetPassword(email: "") {
message
status
}
}
  1. resetOvesUserPassword: Resets the password of a user based on the provided token and new password. It returns a message and status indicating the success of the password reset. This mutation is used for resetting the user password. The Token is the one sent to the email when run the mutation checkOvesUserEmailForResetPassword.
mutation {
resetOvesUserPassword(resetLoginUserPasswordInput:{
token:""
password:""
}) {
message
status
}
}

Client

  1. adminRegisterDistributor: Used by admins to register new distributors to the ERM system
mutation {
adminRegisterDistributor(
adminRegisterDistributor: {
contactRole: "DISTRIBUTOR"
distributorAddress: {
city: "Nairobi"
country: "Kenya"
locationAddressDto: {
inputAddressLatitude: -17.824858
inputAddressLongitude: 31.053028
}
postcode: "12345"
srpc: "String"
street: "Kenya"
unit: "Kenya"
}
distributorDescription: "Standard PAYG Distribution Established in 2021"
distributorName: "Distributor Namw"
distributorType: DISTRIBUTOR
email: "[distributor@gmail.com](mailto:distributor@gmail.com)"
roleId: "61766d39f74eeb440e34f096"
}
){
_id
}
}
  1. signInClient: Allows a distributor to sign in using their email and password. It returns the distributor's ID and access token upon successful authentication.
mutation {
signInClient(signInCredentialsInput:{
email:""
password:""
}){
_id
accessToken
}
}
  1. checkDistributorEmailForResetPassword: Sends a reset password link to the distributor's email if it exists. It returns a message and status indicating the success of the operation.
mutation {
checkDistributorEmailForResetPassword(email: "") {
message
status
}
}
  1. resetDistributorPassword: Resets the password of a distributor based on the provided token and new password. It returns a message and status indicating the success of the password reset. The Token is the one sent to the email when run the mutation checkDistributorEmailForResetPassword.
mutation {
resetDistributorPassword(resetLoginUserPasswordInput:{
token:""
password:""
}) {
message
status
}
}

These mutations are part of an authentication system that enables user and client registration, login, password reset, and other related operations within the application. The specific implementation details and usage context may vary depending on the overall application architecture and requirements.

Distributor Staff and Agent Functionality

This section of the documentation outlines the functionalities and roles of Distributor Staff and Agents within our system. Distributor Staff, deriving their permissions from the Master Distributor, have extensive access rights, including the creation of Agents. Agents' access and control are limited and defined by the permissions allocated to them by the Distributor Staff.

Distributor Staff Registration and Permissions

Key functionalities

  1. distributorRegisterDistributorStaff - Used to register new distributor staffs to the ERM system.
mutation{
  distributorRegisterDistributorStaff(distributorRegisterDistributorStaffInput:{
    staffID:""
    subRoleId: ""
    hireDate:DateTime
    officeAddress:AddressDto
    email: ""
    firstName:"
    lastName:""
    gender:""
    age: Float
    staffContact:ContractDto
    staffAddress:AddressDto
  })
}

● Purpose: To register new Distributor Staff.

● Input: distributorRegisterDistributorStaffInput

● Returns: DistributorStaff

  1. updateDistributorStaff : Purpose is to update the details of existing Distributor Staff.

● Input: updateDistributorStaffInput

● Returns: DistributorStaff

  1. deleteDistributorStaff : Its purpose is to remove a distributor staff from the system.

● Input: distributorStaffId

● Returns: String (confirmation message)

  1. signUpDistributorStaff : Used to complete the registration process for a Distributor Staff.

● Input: signUpDistributorStaffInput

● Returns: User

Agent

  1. distributorStaffRegisterAgent : Used to register a new Agent under the Distributor Staff.

● Input: distributorStaffRegisterAgentInput

● Returns: Agent

  1. updateAgent : It’s used to update an Agent’s details

● Input: updateAgentInput

● Returns: Agent

  1. deleteAgent : Used to delete an Agent from the system.

● Input: agentId

● Returns: String

Asset and Permissions Assignment

  1. assignAssetAccountToAgentByDistributorStaff and removeAssetAccountFromAgentByDistributorStaff : They are used to assign or remove asset accounts to or from an Agent.

● Input: assignAssetAccountToAgentInput

● Returns: Success

  1. assignItemToAgent and removeItemFromAgent : Used to assign or remove items to or from an agent.

● Input: assignItemToAgentInput

● Returns: Success

  1. assignPermissionsToAgent and deletePermissionsFromAgent : Are used to assign or delete permissions for an Agent

● Input: assignPermissionToSubRoleInput

● Returns: Success.

Queries for Retrieving Information

  1. Query: getAllAgentsForSpecificDistributorStaff and getAllDistributorStaff : Are used to retrieve lists of all Agents or Distributor Staff.
  2. Parameters: search, before, after, first, last
  3. Returns: GetAllAgentsResponse or GetAllDistributorStaffResponse
  4. Query: getSpecificDistributorStaff and getSpecificAgent : Are used to retrieve details of a specific Distributor Staff or Agent.
  5. Input: id
  6. Returns: DistributorStaff or Agent

Workflow

  • Registration Process: The registration of Distributor Staff and Agents is initiated by the Master Distributor and Distributor Staff respectively. An email is sent to the invitee to complete the registration.
  • Permission Allocation: Distributor Staff allocate permissions to Agents based on the access rights granted to them by the Master Distributor. These permissions can be assigned in bulk or individually.
  • Asset and Item Management: Distributor Staff can assign and remove asset accounts and items to/from Agents. The assigned permissions dictate the Agent's functional scope related to these assets and items.

Additional Notes

  • Access Limitations: Distributor Staff cannot create another Distributor Staff or generate certain codes (DAYSCODE, RESETCODE, FREECODE) via the API, though they can do so on the ERM portal.
  • Permissions Hierarchy: The permissions available to the Distributor Staff are a subset of those held by the Master Distributor. This hierarchy governs the scope of permissions that can be passed on to Agents.