API User Guide

The paiyroll® API provides OpenAPI 3.0 compliant programmatic access to selected functions of the system. Access is provided to:

  • The OpenAPI 3.0 schema

  • The selected paiyroll® functions

Access is possible programmatically, or using an interactive workbench, or command line tools. Login as an administrator to use the Swagger workbench to interactively test and develop against the API.

Setting up OAuth 2.0

API access is controlled using OAuth 2.0. To get started, OAuth 2.0 requires an application to be created. You can create and manage OAuth 2.0 applications using the Swagger workbench. When setting up your applications you will need to configure several settings:

Application settings

Setting

Description

Name

A descriptive string. This allows you to have multiple applications for different purposes.

Client id

A random string which is generated for you. Used when gaining access using this application. Keep this string securely.

Client secret

A password which is generated for you. Used when gaining access using this application. You must copy this value before you click save. Keep this string securely.

Client type

Set to Confidential.

Authorization grant type

Set depending on how you plan to use this application. Choose:

  • Authorization code. For prototyping using the Swagger workbench Try it out feature and production use.

  • Resource owner password-based for use with “curl” and similar command line tools. This is useful when prototyping using the command line.

Redirect URIs

Enter the full URI to be used. The URI must match the entry in Servers:

http://<address and any port>/.../oauth2-redirect.html

The URI can be copied from the Swagger workbench.

Algorithm

No OIDC Support

Using the Swagger workbench

The Swagger workbench can be used to:

  • Download the API schema in OpenAPI 3.0 format using YAML.

  • Review the API documentation.

  • Prototype API usage using the Try it out feature. When using this:

    1. Ensure the application has been configured with the correct Authorization grant type for this usage.

    2. Create an access token using Authorize.

    3. Ensure the Media type for the response is set as required.

    4. Click Try it out. If the error [unauthorized_client]: no accessCode received from the server is seen, then check the Authorization grant type setting is Authorization code.

Prototyping using the command line

An example of using the curl command:

  1. Ensure the application has been configured with the correct Authorization grant type for command line usage.

  2. Use a command like the following to get the OAuth 2.0 access token, replacing the values marked with <> with the correct ones for your configuration:

    curl -X POST \
    -d "grant_type=password&username=<administrator email>&password=<administrator password>" \
    -u "<client id from application>:<client secret from application>" \
   https://login.paiyroll.com/api/auth/token/

  3. The output of the command should be something like this:

    {"access_token": "ee0g0NQpEHBdZTjuMna75pkdvtFbJU", "expires_in": 36000, "token_type": "Bearer", "scope": "read write", "refresh_token": "HiGMFTOMEptWtObu0qkjWEmpjp4kW5"}

    If the output is {“error”: “unauthorized_client”} then check the Authorization grant type setting is Resource owner password-based, and that the correct administrator and client details are provided.

  4. Use the access_token to invoke the API of interest:

    curl -L -H "Authorization: Bearer <access_token>" https://login.paiyroll.com/api/v1/company