Call the endpoint of a REST API job with Bearer authentication

In this scenario, it's assumed that a REST API job is created in HULFT Square and the endpoint to execute that job is called from a program in your environment.

For the authentication when you call the endpoint, Bearer authentication is used.

You can update access tokens used for authentication with the following method:

Update from PERSONAL SETTINGS > Access Token of HULFT Square
Update from an API in a program in your environment

This scenario describes the method for updating the access tokens used for authentication directly from an API in a program in your environment instead of from the Web screen of HULFT Square.

Description

This section describes the procedure from creating a REST API job that executes a script in HULFT Square to preparing Bearer authentication in your environment and calling the job execution endpoint.

Follow the steps below to do so.

0. Preparation

1. Obtain the access token with the Login API

2. Execute the endpoint of the REST API job from your HTTP client

2. 1 Update an access token

2. 2 Execute the endpoint of the REST API job from your HTTP client

3. Check the execution results

Procedures

0. Preparation

Create a REST API job that executes a script in HULFT Square.

(1) Create a script to execute on an endpoint of a REST API job

In this scenario, the script created in Create a script that processes a CSV file is used.

(2) Create an API project

Select > API MANAGEMENT > API Projects.
On the API Projects page, select Add API Project.

In step General on the API Projects > Add New page, configure the settings as follows, and then select Next.

Field name	Setting (example)
Name	REST_API_job_PJ
Workspace	Personal
Description	(Optional)
Base path	api-test

In step Summary, confirm the entered contents and select Finish.

(3) Add resources to the API project

On the API Projects page, select the Resources icon.
On the API Projects > REST_API_job_PJ > Resources page, select GET from of Add HTTP method.

In the right layer on the API Projects > REST_API_job_PJ > Resources page, configure the settings as follows and select Apply.

Field name	Setting (example)
Project	sample1
Project version	Set the latest version number.
Script	Script
Response settings
Response code	200
Response body	Text, JSON, data

Settings for other items are optional.

(4) Create an API client

Select > API MANAGEMENT > API Clients.
On the API Clients page, select Create API Client.

In step General on the API Clients > Add New page, configure the settings as follows, and then select Next.

Field name	Setting (example)
Name	API_Client
Description	(Optional)
Permitted users	Select the users to call the endpoint from the member list (possible to choose multiple users).
IP allowlist	(Optional)

In step Summary, confirm the entered contents and select Finish.

(5) Create a REST API job

Select > JOBS > REST API Jobs.
On the REST API Jobs page, select Add.

In step General on the REST API Jobs > Add New page, configure the settings as follows, and then select Next.

Field name	Setting (example)
Workspace	Personal
API project	REST_API_job_PJ
API project version	Set the latest version number.
Profile	Choose a profile.
Description	(Optional)

In step API settings, configure the settings as follows, and then select Next.

Field name	Setting (example)
API clients	API_Client

In step Service to run scripts, configure the settings as follows, and then select Next.

Field name	Setting (example)
Service to run scripts	Set the name of the HULFT Integrate service that is running.

In step Summary, confirm the entered contents and select Finish.

An endpoint is created automatically.
On the REST API Jobs page, select the Information icon.
On the REST API Jobs > REST_API_job_PJ page, copy the URL for the endpoint, and make a note of it in a text editor such as notepad.

Use the copied URL for the endpoint in step 2. 2 .

1. Obtain the access token with the Login API

To update a token used for authentication directly from the API in a program in your environment instead of from the Web screen of HULFT Square, you must obtain the access token required for authentication in advance.

Obtain the access token with the Login API as shown below.

Specification method

POST /v1/users/login

The endpoint is as follows.

https://app.square.hulft.com/v1/users/login

In Body, specify the email address and password in the JSON format.

Request body

{ 
    "email":"abc@example.com", 
    "password":"*******" 
}

If you send the above request body to the endpoint, an access token (hereafter the access token obtained with Login API) is obtained in the response body as follows.

Response body

{ 
    "accessToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 
    "expiresIn": 3600, 
    "tokenType": "Bearer", 
    "challenge": false, 
    "email": "", 
    "session": "" 
}

After that, if you want to access the API, you must specify the access token obtained with Login API in the Authorization header to obtain access permission.

2. Execute the endpoint of the REST API job from your HTTP client

2. 1 Update an access token

2. 2 Execute the endpoint of the REST API job from your HTTP client

2. 1 Update an access token

Access token has an expiration date. If the token has expired, update Access token before you send a request to the endpoint of the REST API job.

The default expiration date for Access token is 60 minutes. With the Admin permissions, you can set it to a maximum of one day.

Update Access token using Refresh token obtained from PERSONAL SETTINGS > Access Token of HULFT Square.

= Remarks =

For details on how to obtain Refresh token from PERSONAL SETTINGS > Access Token of HULFT Square, refer to Personal settings.

Specification method

PUT /v1/rest-api-token

The endpoint is as follows.

https://app.square.hulft.com/v1/rest-api-token

Authorization: Bearer <Access token obtained with Login API>

In Body, specify the Refresh token in JSON format.

Request body

{
    "refreshToken":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" （*）
}

In refreshToken, specify Refresh token obtained from PERSONAL SETTINGS > Access Token of HULFT Square.

If you send the above request body to the endpoint, Access token is updated as follows.

Response body

{ 
    "expires": 1669798184, 
    "accessToken":"ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ", 
    "refreshToken":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", 
    expiresIn: 3600, 
    tokenType: "Bearer", 
    status: "Valid", 
    updated: 1669794 
}

2. 2 Execute the endpoint of the REST API job from your HTTP client

Call the HTTP method and URL that you created in > JOBS > REST API Jobs of HULFT Square from an HTTP client in your environment.

Specification method

The endpoint is as follows.

https://<your domain name>.square.hulft.com/<profile name>/<base path>/<resource path>

Authorization: Bearer <accessToken>  (*)

In <accessToken>, specify the Access token you obtained in step 2. 1 .

As a result, the script set in the REST API job is executed.

3. Check the execution results

If the request is successfully executed, the value "200 (OK)" is returned for the HTTP code.

If a 400 series error such as 400 or 401 occurs, make sure the correct value is set for the request information, such as the endpoint, access token, and request body. Also, for 403, check the settings of the API client.

Check the execution results of the script on the page in > SERVICE EVENTS > HULFT Integrate.

On the HULFT Integrate page, you can check it by filtering it with Add filter as shown below.

When the execution_id is output to the response body

You can check it by specifying the execution_id to Exec ID.
When the execution_id is not output to the response body

You can check the execution results by specifying Project or Script and identifying them using the time such as Start date time.

= Remarks =

For details about the error response for REST API jobs, refer to Error response for REST API jobs.