Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0

Abstract

How to test the new Web API (OpenAPI) introduced in Access Server 3.0 to control functionalities remotely through endpoints.

Overview

This tutorial explains how to test the new Web API (OpenAPI) introduced in Access Server 3.0, which lets you control Access Server functionalities remotely through REST API endpoints.

Prerequisites

An installed Access Server running 3.0.x.
Console access and the ability to get root privileges.
A remote device where you can run the API calls.

View the API specification

You can view the API specification in two ways:

Option 1: Enable API documentation in Access Server

Connect to the console and get root privileges.

Run the following commands to enable the API documentation:

sacli --key "openapi.web_access" --value 1 ConfigPut
sacli start

Open the following URL in your browser:
```
https://203.0.113.5:943/api/docs
```
Replace 203.0.113.5 with your Access Server IP address.

Important

This enables the browser-based documentation view and is an optional step. The API is active by default in Access Server 3.0.

Option 2: Review the API documentation

For details on the Access Server API schema and endpoints, see the Access Server API documentation.

Test the new API

For the purposes of this tutorial, we'll demonstrate how to create a new user using the /users/create endpoint.

Method 1: Run API calls with cURL

Tip

You can use this method directly in your Access Server or with a remote machine.

Generate an authentication token for an admin user:

sacli --user openvpn1 GenerateAuthToken

1	Where `openvpn` is a user with admin privileges. We need a user with admin privileges to generate the needed Authentication Token for this method.

This outputs an authentication token, for example:

root@openvpnas:~# sacli --user openvpn GenerateAuthToken
{'expirytime': 1761002715,
 'maxsessiontime': 1761016515,
 'token': 'SESS_TOKEN_t5RT2/S18pEU9PFKBWoXL40NNZring0ntjmSa6hbI6d9SFDxxFF8OEII+qizKaY+J4ub4qT+jDHFuPQ9zHgI+mvRzLu0hsuB+/0BEXFcYeZCHGzg+TE75Fvkn+NV'}

Alternate first step:

You can also generate an authentication token for an admin user using cURL.

Run the following command where openvpn is an admin user and pass4openvpn is the user password:

curl -X 'POST' 'https://203.0.113.5:943/api/auth/login/userpassword' -H 'accept: */*' -H 'Content-Type: application/json' -d '{"request_admin": true, "username": "openvpn","password": "pass4openvpn"}' -k

Ensure the user has admin privileges to generate the necessary authentication token for this alternate method.

This outputs an authentication token. Example output:

root@openvpnas:~# curl -X 'POST' 'https://203.0.113.5:943/api/auth/login/userpassword' -H 'accept: */*' -H 'Content-Type: application/json' -d '{"request_admin": true, "username": "openvpn","password": "pass4openvpn"}' -k
{"auth_token":"SESS_TOKEN_9EtCbf/qQbfmox6k6NvAGomUMCR+x3wLAGdzIK/uG+mm00MZD9mxQ4aMjttoebzKRpmAt1ShH4XEgh9pujVgxns2Bbda3SF84vuSeqmZnOkJ1VSiPreCznjQ","expires_after":"2025-10-23T21:00:23.000000Z","renewable_until":"2025-10-24T00:50:23.000000Z","user_properties":{"requires_mfa_enrollment":false,"user_type":"admin","allowed_profiles":["userlogin"],"enforce_strong_passwords":true,"username":"openvpn","allow_password_change":true}}

Use the token to create a new user:

curl -k --location 'https://203.0.113.51:943/api/users/create' \
--header 'X-OpenVPN-As-AuthToken: <Authentication Token here>2' \
--header 'Content-Type: application/json' \
--data '{
    "name": "brandonqa3"
}'

1	Replace `203.0.113.5` with your Access Server IP.
2	Replace `<Authentication Token here>` with the token from the previous step.
3	Replace `brandonqa` with the desired username.

Verify that the user was created:

sacli --pfilt brandonqa UserPropGet

Example output:

{
  "brandonqa": {
    "type": "user_connect"
  }
}

Method 2: Run API calls using 'apicall'

Tip

You can also use sacli's built-in apicall function to perform API requests directly from Access Server.

Run the following command:

sacli --method POST --url 'api/users/create' --value '{"name": "brandonqa1"}' apicall

1	Replace `brandonqa` with the username you want to create.

Example output:
```
HTTP-Status: 201
```