Guides

User Types

Suggest Edits

Introduction

This guide allows you to manage administrative users of your company(ies) within our system. It provides a comprehensive walkthrough of the endpoints available for managing multi-admins and admin users, detailing their use cases, functionalities, and how to use them effectively.

Prerequisites

Before you begin, ensure you have the following:

  • API Credentials: An API key or OAuth token with the necessary permissions to manage admins.
  • Company ID: The unique identifier of the company whose logins you want to manage.
  • HTTP Client: Tools like curl, Postman, or any programming language with HTTP support.
  • JSON Parser: Ability to parse JSON responses.

Overview of Admin Types and Permissions

Worklio supports three user types but two administrative user types:

  1. System-level users or Multi-Admins
  2. Admin level users
  3. Employee-level users

System-level users

These are system-wide admin users with super-user accounts with broader permissions, potentially including access to multiple companies or system configurations. Usually, the system generates only one of such accounts during developer registration. However, you can create more in the production environment by contacting our support.

The system automatically adds all companies this user creates to his access list, and he has full admin rights over them. The system user is also suitable for machine-2-machine API usage.

Admin-level users

These users have a standard admin account. An admin is an employee of the company who can perform administrative operations and tasks, such as hiring and terminating employees, running payrolls, and so on. Admins have full rights to the company where they are employed.

Admin rights are not limited; you can set them for any number of employees. Just be aware that admin users see other users’ payrolls. So, handle it carefully and set this only for company admins.

Employee-level users

The system gives this access type to all company employees. Employees can access only their data and payrolls. Due to regulatory reasons, some update operations are not allowed for employees, even on their own data.

Use Cases

  • Admin-level users:

    • Manage company-specific settings and data.
    • Access is limited to the company they are associated with.

  • System-level users:

    • Manage multiple companies.
    • Access to system-wide configurations and settings.
    • Higher level of permissions and responsibilities.

Understanding the distinction between these admin types is crucial for assigning appropriate permissions and maintaining security.

Admin-level Users Management

1. List Company Logins

Endpoint: GET /wep/companies/{companyId}/logins

Description: This endpoint retrieves a list of all logins (admins) associated with a specific company.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/logins
Authorization: Bearer YOUR_API_TOKEN

Example Response:

[
  {
    "loginId": "login123",
    "username": "jdoe",
    "email": "[email protected]",
    "status": "active",
    "roles": ["manager", "editor"]
  },
  {
    "loginId": "login124",
    "username": "asmith",
    "email": "[email protected]",
    "status": "blocked",
    "roles": ["viewer"]
  }
]

Usage:

  • Use this endpoint to get a list of all company logins.
  • Review the list to manage existing users or audit user access.

2. Create a Company Login

Endpoint: POST /wep/companies/{companyId}/logins

Description: Call this endpoint to create a new login (admin user) for a company.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/logins
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "username": "mjones",
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "roles": ["editor"],
  "firstName": "Mary",
  "lastName": "Jones"
}

Example Response:

{
  "loginId": "login125",
  "message": "Company login created successfully."
}

Usage:

  • Use this endpoint to add new admin users to a company.
  • Assign appropriate roles to control permissions.
  • Ensure they follow password qualities for security.

3. Retrieve Company Login Details

Endpoint: GET /wep/companies/{companyId}/logins/{loginId}

Description: This endpoint successfully returns the details of a specific admin user.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/logins/login125
Authorization: Bearer YOUR_API_TOKEN

Example Response:

{
  "loginId": "login125",
  "username": "mjones",
  "email": "[email protected]",
  "status": "active",
  "roles": ["editor"],
  "firstName": "Mary",
  "lastName": "Jones",
}

Usage:

  • View detailed information about a specific login.
  • Check user status and roles.

4. Update a Company Login

Endpoint: PATCH /wep/companies/{companyId}/logins/{loginId}

Description: Updates information for a specific company login.

Example Request:

PATCH https://apidocs.worklio.com/wep/companies/123456/logins/login125
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "email": "[email protected]",
  "roles": ["editor", "manager"]
}

Example Response:

{
  "message": "Company login updated successfully."
}

Usage:

  • Update user information such as email or roles.
  • Modify permissions by updating roles.

5. Block Company Logins

Endpoint: PATCH /wep/companies/{companyId}/logins/block

Description: Blocks one or multiple company logins, preventing them from accessing the system.

Example Request:

PATCH https://apidocs.worklio.com/wep/companies/123456/logins/block
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "loginIds": ["login125", "login124"],
  "reason": "Security policy violation."
}

Example Response:

{
  "message": "Company logins blocked successfully.",
  "blockedLogins": ["login125", "login124"]
}

Usage:

  • Use this endpoint to block users due to security issues or policy violations.
  • Provide a reason for auditing purposes.

System-level Users Management

1. List Admin Users

Endpoint: GET /wep/admins

Description: Retrieves a list of all system-level users.

Example Request:

GET https://apidocs.worklio.com/wep/admins
Authorization: Bearer YOUR_API_TOKEN

Example Response:

[
  {
    "adminId": "admin001",
    "username": "admin.jdoe",
    "email": "[email protected]",
    "status": "active",
    "roles": ["superadmin"]
  },
  {
    "adminId": "admin002",
    "username": "admin.asmith",
    "email": "[email protected]",
    "status": "active",
    "roles": ["support"]
  }
]

Usage:

  • Use this endpoint to get a list of all multi-admin users.
  • Manage system-wide administrators and their access.

2. Create a Multi-admin User

Endpoint: POST /wep/admins

Description: Creates a new multi-admin user in the system.

Example Request:

POST https://apidocs.worklio.com/wep/admins
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "username": "admin.mjones",
  "email": "[email protected]",
  "password": "AnotherSecurePass123!",
  "roles": ["support"],
  "firstName": "Mary",
  "lastName": "Jones"
}

Example Response:

{
  "adminId": "admin003",
  "message": "Admin user created successfully."
}

Usage:

  • Add new system administrators.
  • Assign appropriate roles to control access and permissions.

3. Retrieve Multi-admin User Details

Endpoint: GET /wep/admins/{id}

Description: Retrieves details of a specific multi-admin user.

Example Request:

GET https://apidocs.worklio.com/wep/admins/admin003
Authorization: Bearer YOUR_API_TOKEN

Example Response:

{
  "adminId": "admin003",
  "username": "admin.mjones",
  "email": "[email protected]",
  "status": "active",
  "roles": ["support"],
  "firstName": "Mary",
  "lastName": "Jones",
  "lastLogin": "2023-09-16T08:22:10Z"
}

Usage:

  • View detailed information about an admin user.
  • Monitor admin activity and status.

4. Update a Multi-admin User

Endpoint: PATCH /wep/admins/{id}

Description: Updates information for a specific multi-admin user.

Example Request:

PATCH https://apidocs.worklio.com/wep/admins/admin003
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "email": "[email protected]",
  "roles": ["support", "manager"]
}

Example Response:

{
  "message": "Admin user updated successfully."
}

Usage:

  • Modify multi-admin user details.
  • Update roles to change permissions.

5. Block a Multi-admin User

Endpoint: PATCH /wep/admins/{id}/block

Description: Blocks a multi-admin user, preventing them from accessing the system.

Example Request:

PATCH https://apidocs.worklio.com/wep/admins/admin003/block
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "reason": "Unauthorized access attempt."
}

Example Response:

{
  "message": "Admin user blocked successfully.",
  "adminId": "admin003"
}

Usage:

  • Block multi-admin users due to security concerns.
  • Provide a reason for record-keeping.

6. Activate a Multi-admin User

Endpoint: PATCH /wep/admins/{id}/activate

Description: Activates a blocked multi-admin user, restoring their access.

Example Request:

PATCH https://apidocs.worklio.com/wep/admins/admin003/activate
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "note": "Issue resolved; access restored."
}

Example Response:

{
  "message": "Admin user activated successfully.",
  "adminId": "admin003"
}

Usage:

  • Reactivate a multi-admin user after resolving issues.
  • Document the activation for auditing purposes.

Conclusion

Managing admin users and multi-admins is crucial for maintaining the security and integrity of your company. By utilizing the endpoints provided in the reference docs, developers can effectively create, update, and manage administrative users.

For further assistance or inquiries, contact support.

Updated about 2 months ago