--- title: 'Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0' canonical: https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0/ product: Access Server Docs description: How to test the new Web API (OpenAPI) introduced in Access Server 3.0 to control functionalities remotely through endpoints. --- # Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0 ## 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 1. Connect to the console and get root privileges. 2. Run the following commands to enable the API documentation: ``` sacli --key "openapi.web_access" --value 1 ConfigPut sacli start ``` 3. 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](https://openvpn.net/as-docs/rest-api.md). ## 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 run these API calls directly on your Access Server or from a remote machine. 1. Generate an authentication token for an admin user: ``` sacli --user openvpn GenerateAuthToken ``` 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'} ``` > **Tip** > > **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}} > ``` 2. Use the token to create a new user: ``` curl -k --location 'https://203.0.113.5:943/api/users/create' \ --header 'X-OpenVPN-As-AuthToken: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "brandonqa" }' ``` Replace `203.0.113.5` with your Access Server IP. Replace `` with the token from the previous step. Replace `brandonqa` with the desired username. 3. 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. 1. Run the following command: ``` sacli --method POST --url 'api/users/create' --value '{"name": "brandonqa"}' apicall ``` Replace `brandonqa` with the username you want to create. - Example output: ``` HTTP-Status: 201 ``` 2. Verify that the user was created: ``` sacli --pfilt brandonqa UserPropGet ``` - Example output: ``` { "brandonqa": { "type": "user_connect" } } ``` ### Method 3: Run API calls using the embedded Swagger UI from Access Server #### Sign in to the API with an auth token 1. [Enable the API documentation](https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0.md) for your Access Server. 2. Open the API docs in your browser: ``` https://203.0.113.5:943/api/docs ``` Replace `203.0.113.5` with your Access Server IP address. 3. In the **auth** section, click to expand `/auth/login/userpassword`. 4. Click **Try it out**. - The **Edit Value** box displays. 5. Replace the schema values with these, where `openvpn` is an admin user and `pass4openvpn` is the user password: ``` { "request_admin": true, "username": "openvpn", "password": "pass4openvpn" } ``` 6. Click **Execute**. 7. The response displays with the **auth\_token** in the **Response body**: 8. Copy the **auth\_token** value. 9. Scroll back up and click **Authorize**. - The **Available authorizations** modal displays. 10. Under **AuthToken (apiKey)**, paste the authentication token in the **Value** text box. 11. Click **Authorize**. - You can now run API calls. #### Run API calls 1. Scroll down to the API endpoint `/users/create`. 2. Click **Try it out**. - The **Edit Value** box displays. 3. Replace the schema values with the following, where you replace `brandonqa` with the username you want to create. ``` { "name": "brandonqa" } ``` 4. Click **Execute**. - The response displays with code 201 — the user was created successfully. 5. Verify the user was created with the following command on the Access Server command line with root privileges: ``` sacli --pfilt brandonqa UserPropGet ``` - Example output: ``` { "brandonqa": { "type": "user_connect" } } ``` --- Prev: [APIs and Automation](https://openvpn.net/as-docs/v3/tutorials/apis-and-automation.md) Next: [Tutorial: Using the Command Line to Bulk Update User Configurations](https://openvpn.net/as-docs/v3/tutorials/tutorial--bulk-update-user-configurations.md) Index: https://openvpn.net/as-docs/llms.txt