---
title: REST API
canonical: https://openvpn.net/as-docs/rest-api/
product: Access Server Docs
---
# REST API
## Web API v0.2
The Access Server Web API v0.2 is available in Access Server 3.2.0 and newer. For the v0.1 reference, which covers Access Server 3.0.0–3.1.0, see [Web API v0.1](https://openvpn.net/as-docs/rest-api/#web-api-v0-1).
### OpenVPN Access Server Web API v0.2
This API provides the functionality required to download connection profiles, manage clients, and operate the Admin Web UI programmatically.
#### Conventions
| **Element** | **Convention** |
| --- | --- |
| Field names | snake\_case |
| URLs | kebab-case |
| Other identifiers | camelCase |
> **Important**
>
> - This API is under active development. Endpoints and parameters may change without notice.
> - The API supports proxying requests to other nodes in an Access Server cluster. Proxying is only applicable to admin endpoints.
> - We have made every effort to keep this documentation accurate, but minor discrepancies with the implementation may exist.
#### Swagger UI
To browse this API interactively, navigate to `/api/docs` on your Access Server. Ensure you've enabled access by setting `openapi.web_access` to `1`:
```
sacli --key "openapi.web_access" --value 1 ConfigPut
```
Alternatively, set this in the Admin Web UI Config Editor.
#### Base URLs
- `/api`
- `https://your-access-server.example.com/api/`
### Authentication
- API Key (AuthToken)
- Parameter Name: **X-OpenVPN-As-AuthToken**, in: header. This is an opaque token that allows using the authenticated method. The token will expire after a certain amount of time unless it is renewed through the renewal API. While we might use a JWT for this, the API consumer should not assume anything about the format or content of this string. JWT with default encryption/authentication appears not to be FIPS compatible.
- API Key (ProfileDownloadToken)
- Parameter Name: **token**, in: query. This is a string-token that can be used to download OpenVPN Connection Profile or installer file. Typically, e.g. for installer download and OpenVPN connection profile download, this token is generated as a token, that can be used only once.
- HTTP Authentication, scheme: basic a basic auth with user and password. This methods uses a fairly non-standard challenge/resposne method if required that is documented under https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#challengeresponse-authentication
### auth
Endpoints for handling authentication to the API. All successful login calls return an opaque authentication token (auth token).
#### authByUserAndPw
`POST /auth/login/userpassword`
Authenticates using a username and password. Returns an auth token for further requests. Optionally, a TOTP token can be provided.
##### Body parameter
```json
{
"request_admin": true,
"username": "string",
"password": "string",
"totp": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [userAndPwLogin](https://openvpn.net/as-docs/rest-api/#userandpwlogin) | false | none |
| » **anonymous** | body | [loginParameters](https://openvpn.net/as-docs/rest-api/#loginparameters) | false | none |
| »» request\_admin | body | boolean | false | Whether this login should request admin privileges. Without this set to true, even admin users will not be granted admin privileges after login. |
| » **anonymous** | body | [userAndPw](https://openvpn.net/as-docs/rest-api/#userandpw) | false | none |
| »» username | body | string | true | The user name for login. Note that if this is case-sensitive or not depends on the OpenVPN Access Server configuration. |
| »» password | body | string | true | The password for login in clear text |
| »» totp | body | string | false | Optional TOTP token for the user when wishing to do all MFA credentials in one go. |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Authentication successful. Returns user properties and an auth token. | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | MFA is required, or SAML login is expected. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Invalid credentials or user access denied. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 409 | [Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8) | MFA enrollment is required. Returns an intermediate auth token for enrollment. | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse) |
##### Response Schema
Status Code **401**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » MFAChallenge | [MFAChallenge](https://openvpn.net/as-docs/rest-api/#mfachallenge) | false | none | none |
| »» echo | boolean | true | none | If true, the entered code should be displayed in cleartext. Otherwise masked like a password. |
| »» challenge | string | true | none | The text presented to the user when asking for the challenge. |
| »» challenge\_context | string | true | none | Often authentication backends require the challenge to be answered in the same session as the initial user/password. This allows tying the MFA answer to the initial authentication attempt. |
This operation does not require authentication
```javascript
const inputBody = '{
"request_admin": true,
"username": "string",
"password": "string",
"totp": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/userpassword',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authMFASession
`POST /auth/login/mfaauth`
Provides an API to continue the authentication after an MFA challenge. This must have the same loginParameters as the original login request.
##### Body parameter
```json
{
"request_admin": true,
"response": "pa$$word",
"challenge_context": "FJAIIXMAIOFLGAK23",
"username": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [MFAResponse](https://openvpn.net/as-docs/rest-api/#mfaresponse) | true | none |
| » **anonymous** | body | [loginParameters](https://openvpn.net/as-docs/rest-api/#loginparameters) | false | none |
| »» request\_admin | body | boolean | false | Whether this login should request admin privileges. Without this set to true, even admin users will not be granted admin privileges after login. |
| » **anonymous** | body | [MFAChallengeResponse](https://openvpn.net/as-docs/rest-api/#mfachallengeresponse) | false | none |
| »» response | body | string(password) | false | the user’s response to the MFA challenge |
| »» challenge\_context | body | string | false | The challenge context that was in the MFAChallenge. |
| »» username | body | string | true | The user name for login |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Authentication successful. | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Invalid MFA response. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const inputBody = '{
"request_admin": true,
"response": "pa$$word",
"challenge_context": "FJAIIXMAIOFLGAK23",
"username": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/mfaauth',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authBySAMLAssertion
`POST /auth/login/saml-assertion`
Authenticates using a SAML assertion. Returns an auth token.
##### Body parameter
```json
{
"request_admin": true,
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [samlLogin](https://openvpn.net/as-docs/rest-api/#samllogin) | true | none |
| » **anonymous** | body | [loginParameters](https://openvpn.net/as-docs/rest-api/#loginparameters) | false | none |
| »» request\_admin | body | boolean | false | Whether this login should request admin privileges. Without this set to true, even admin users will not be granted admin privileges after login. |
| » **anonymous** | body | [samlLoginAssertion](https://openvpn.net/as-docs/rest-api/#samlloginassertion) | false | none |
| »» assertion | body | string(xml) | true | SAML Assertion in xml format , encoded as base64-string |
| »» relay\_state | body | string | false | Optional relay state identifying the type of SAML request. If not passed or empty, defaults to cws |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Authentication successful. | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The RelayState is incorrect or the SAML assertion is invalid. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | The authentication assertion could not be processed: the status was unhandled, unknown, or invalid. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Access denied due to user/account restrictions, invalid SAML config, or profile requiring user/password based authentication. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const inputBody = '{
"request_admin": true,
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/saml-assertion',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authRenewToken
`POST /auth/token/renew`
Provides a new auth token to extend the lifetime of the previous token.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Token renewed successfully. | [authTokenResponse](https://openvpn.net/as-docs/rest-api/#authtokenresponse) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | The old token has expired and cannot be renewed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Token renewal is no longer allowed. | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/token/renew',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### changePasswordLocalUser
`POST /auth/password/change`
Allows changing a local user's password. To verify that the user knows the old password, this endpoint requires an auth token issued very recently (within ~30 seconds) or an admin-issued token. Only tokens that meet this freshness requirement are accepted. After a successful password change, the client must request a new auth token.
##### Body parameter
```json
{
"username": "string",
"new_password": "pa$$word",
"no_session_invalidation": true
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Password changed successfully. | Inline |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | Authentication failed. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Auth token is not recent enough, or the new password does not meet security requirements. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » detail | string | false | none | none |
Status Code **401**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » detail | string | false | none | none |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"username": "string",
"new_password": "pa$$word",
"no_session_invalidation": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/password/change',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"detail": "string"
}
```
#### enrollUserMFA
`POST /auth/mfa/enroll`
Enrolls a user in MFA using a valid MFA token. If successful, the API returns a fully authenticated auth token that can be used without repeating the login or MFA process. This returns a fully authenticated auth-token for general use if no target user was provided to the API. Otherwise, only the username will be returned. This call also sets the internal totp\_locked (pvt\_google\_auth\_secret\_locked) flag to prevent re-enrollment.
##### Body parameter
```json
{
"token": "string",
"username": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | MFA enrollment was successful. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Provided MFA token is invalid or enrollment failed for another reason. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
###### Enumerated Values
| Property | Value |
| --- | --- |
| user\_type | admin |
| user\_type | user |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"token": "string",
"username": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/mfa/enroll',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
### client-import-api
Endpoints used by compatible OpenVPN clients to import connection profiles from Access Server.
#### get\_\_GetInstallerViaToken
`GET /GetInstallerViaToken`
Downloads a client installer from Access Server using a one-time authentication token. This endpoint is part of the REST API for client configuration and requires a token value that can be obtained from the installer-url endpoint. The client should also specify the installer\_type, and optionally indicate support for TLS-Crypt v2.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Installer file downloaded successfully. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used. | Inline |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The requested installer file was not found on the server, or an unexpected error occurred while downloading. | None |
```javascript
const headers = {
'Accept':'application/octet-stream'
};
fetch('/api/GetInstallerViaToken?installer_type=win_v3',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| token | query | string | false | One-time profile download token |
| tls-cryptv2 | query | boolean | false | Set to true if the client supports TLS-Crypt v2. This setting is only indicates the capbility of the client. It can be ignored if the server sides enforce always TLS-Crypt v2 or the server configuration does not support TLS-Crypt V2. |
| installer\_type | query | [installerType](https://openvpn.net/as-docs/rest-api/#installertype) | true | Type of installer to download. |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| installer\_type | win\_v3 |
| installer\_type | mac\_v3 |
| installer\_type | win |
| installer\_type | mac |
| installer\_type | ios |
| installer\_type | android |
| installer\_type | linux |
##### Response Schema
Status Code **400**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » Type | string | false | none | none |
| » Synopsis | string | false | none | none |
| » Message | string | false | none | none |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 200 | Content-Disposition | string | | none |
| 200 | Content-Length | integer | | none |
To perform this operation, you must be authenticated by means of one of the following methods: ProfileDownloadToken
#### get\_\_GetProfileViaToken
`GET /GetProfileViaToken`
Downloads a connection profile from Access Server using a one-time string token. This endpoint requires a valid profile token. See the ProfileDownloadToken schema for more on token usage.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Connection profile downloaded successfully. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used. | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetProfileViaToken',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| token | query | string | false | One-time profile download token |
| tls-cryptv2 | query | boolean | false | Set to true if the client supports TLS-Crypt v2. This setting is only indicates the capbility of the client. It can be ignored if the server sides enforce always TLS-Crypt v2 or the server configuration does not support TLS-Crypt V2. |
##### Response Schema
Status Code **400**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » Type | string | false | none | none |
| » Synopsis | string | false | none | none |
| » Message | string | false | none | none |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 200 | Content-Disposition | string | | none |
| 200 | VPN-Session-User | string | | none |
| 200 | VPN-Session-Token | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: ProfileDownloadToken
#### get\_\_GetAutologin
`GET /GetAutologin`
Downloads an autologin connection profile using basic authentication. This profile type does not include the `--auth-user-pass directive` and is typically used for unattended or persistent VPN connections. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with connection profile file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used. | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetAutologin',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| tls-cryptv2 | query | boolean | false | Set to true if the client supports TLS-Crypt v2. This setting is only indicates the capbility of the client. It can be ignored if the server sides enforce always TLS-Crypt v2 or the server configuration does not support TLS-Crypt V2. |
##### Response Schema
Status Code **400**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » Type | string | false | none | none |
| » Synopsis | string | false | none | none |
| » Message | string | false | none | none |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 200 | Content-Disposition | string | | none |
| 200 | VPN-Session-User | string | | none |
| 200 | VPN-Session-Token | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: ProfileDownloadBasicAuth
#### get\_\_GetUserlogin
`GET /GetUserlogin`
This endpoint allows a client to download an userlogin profile (a profile requiring user/passwsord on connect `--using auth-user-pass`) with basic authentication. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Userlogin connection profile downloaded successfully. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used. | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetUserlogin',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| tls-cryptv2 | query | boolean | false | Set to true if the client supports TLS-Crypt v2. This setting is only indicates the capbility of the client. It can be ignored if the server sides enforce always TLS-Crypt v2 or the server configuration does not support TLS-Crypt V2. |
| device-id | query | string | false | Unique identifier for the client device. |
##### Response Schema
Status Code **400**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » Type | string | false | none | none |
| » Synopsis | string | false | none | none |
| » Message | string | false | none | none |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 200 | Content-Disposition | string | | none |
| 200 | VPN-Session-User | string | | none |
| 200 | VPN-Session-Token | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: ProfileDownloadBasicAuth
#### get\_\_GetGeneric
`GET /GetGeneric`
Downloads a generic connection profile using basic authentication. This profile is not tied to a specific user and can be used when user-based authentication is not required. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Generic profile downloaded successfully. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used. | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetGeneric',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| tls-cryptv2 | query | boolean | false | Set to true if the client supports TLS-Crypt v2. This setting is only indicates the capbility of the client. It can be ignored if the server sides enforce always TLS-Crypt v2 or the server configuration does not support TLS-Crypt V2. |
##### Response Schema
Status Code **400**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » Type | string | false | none | none |
| » Synopsis | string | false | none | none |
| » Message | string | false | none | none |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 200 | Content-Disposition | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: ProfileDownloadBasicAuth
### profiletoken
Endpoints for managing profile tokens used to generate one-time import URLs. These tokens are also part of the the web-based profile import flow for OpenVPN clients.
#### bulktokenurldelete
`POST /token-url/delete`
Delete multiple profile token URLs by providing their token IDs. The request will only succeed if all token IDs are found.
##### Body parameter
```json
[
"string"
]
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | array\[string\] | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | Token were successfully deleted | None |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | One or more token IDs were not found. No tokens were deleted. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '[
"string"
]';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url/delete',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
### profile
Endpoints for managing connection profiles used by OpenVPN clients.
#### head\_\_openvpn-api\_profile
`HEAD /openvpn-api/profile`
Used by OpenVPN clients to detect whether the server supports web-based login for profile import. This is part of the OpenVPN WebAuth flow. See the OpenVPN webauth API specification https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#detection-of-web-based-profile-download-support for full details.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Redirects to base server URL with headers in the response according to OpenVPN webauth API specification. | None |
```javascript
fetch('/api/openvpn-api/profile',
{
method: 'HEAD'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 302 | Ovpn-WebAuth | string | | Token indicating if WebAuth is supported. Client uses this to trigger browser-based import. |
This operation does not require authentication
#### get\_\_openvpn-api\_profile
`GET /openvpn-api/profile`
This endpoint is used by OpenVPN clients, not the Client Web UI, to initiate the profile import process. It differs from /api endpoints and redirects the client to the UI login page as defined in the OpenVPN API spec https://github.com/OpenVPN/openvpn3/blob/master/doc/webautha.md#detection-of-web-based-profile-download-support.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Redirect to http://server\_addres/login?relay\_state=profile | None |
This operation does not require authentication
```javascript
fetch('/api/openvpn-api/profile',
{
method: 'GET'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### getprofilesuser
`POST /profiles/list`
Retrieves a list of all connection profiles for a user. Supports optional filtering, sorting, and pagination parameters for targeted searches. Filters can match specific fields such as username, TLS-Crypt v2 usage, or date ranges. Refer to the request body schema for supported filter options.
##### Body parameter
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"username": {
"operation": "substring",
"value": "vio"
},
"serial": {
"value": 400,
"operation": "less_than"
},
"autologin": {
"value": true
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [profileRequestParameters](https://openvpn.net/as-docs/rest-api/#profilerequestparameters) | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Request succeeded. Returns a list of profiles matching the filter criteria. | Inline |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| » profiles | \[allOf\] | false | none | \[A certificate profile of a user.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails) | false | none | none |
| »»» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial)(int64) | true | none | A string representing the certificate serial number. A string is used instead of an integer to avoid issues with large values in JavaScript, which cannot reliably handle integers larger than 52 bits. |
| »»» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname) | true | none | The certificate common name (CN). |
| »»» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm) | true | none | Specifies the algorithm used for private/public key pair in an X.509 certificate. This is an identifier such as ecp384r1, secp256r1, or secp512r1. For algorithms with variable key lengths, the length is included in the name (e.g., rsa3072). |
| »»» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »»» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »»» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »»» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »»» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | A profile for a user. |
| »»» device\_id | string,null | false | none | Device ID, only used for server-locked v1 profiles |
| »»» comment | string,null | false | none | A user-defined comment |
| »»» profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | false | none | Specifies the connection profile type. |
| »»» tls\_crypt\_v2 | boolean | false | none | This profile uses tls-crypt-v2 |
| »»» last\_used | string,null(date) | false | none | Last date this profile was used (only date is known, there is no more granular resolution) |
| »»» username | string | false | none | User’s name |
###### Enumerated Values
| Property | Value |
| --- | --- |
| profile\_type | autologin |
| profile\_type | userlogin |
| profile\_type | generic |
| profile\_type | epki-generic |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"username": {
"operation": "substring",
"value": "vio"
},
"serial": {
"value": 400,
"operation": "less_than"
},
"autologin": {
"value": true
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/list',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"total": 0,
"profiles": [
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"device_id": "string",
"comment": "My toaster running Doom",
"profile_type": "autologin",
"tls_crypt_v2": true,
"last_used": "2019-08-24",
"username": "string"
}
]
}
```
#### generateUserProfile
`POST /profiles/create`
Generates a new connection profile for the specified user. Supports profile type selection, optional TLS-Crypt v2 support, and an optional comment.
##### Body parameter
```json
{
"username": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [profileRequest](https://openvpn.net/as-docs/rest-api/#profilerequest) | false | none |
| » username | body | [username](https://openvpn.net/as-docs/rest-api/#username) | false | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | true | Specifies the connection profile type. |
| » tls\_crypt\_v2 | body | boolean | false | The client is capable of TLS-Crypt v2 |
| » comment | body | string | false | A user-defined comment |
| » ignore\_missing\_user | body | any | false | if this is flag, which requires admin rights, is set, a profile will be created even if the specified user does not exist. |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Profile created successfully. | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Profile creation not permitted. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 201 | Content-Disposition | string | | none |
| 201 | VPN-Session-User | string | | none |
| 201 | VPN-Session-Token | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"username": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/x-openvpn-profile',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### generateTokenUrl
`POST /token-url`
Generates a one-time-use token URL to download a connection profile for a specific user or create an `openvpn-import://` link for OpenVPN clients. This endpoint requires an admin token if token lifetime or usage limits are specified.
##### Body parameter
```json
{
"lifetime": 1,
"usages": 1,
"profile_type": "autologin",
"username": "niccolo@paganini.it",
"comment": "connected from my iPhone"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [tokenRequestParameters](https://openvpn.net/as-docs/rest-api/#tokenrequestparameters) | false | none |
| » lifetime | body | integer | false | Optional lifetime in seconds that the token should be valid for. Longer lifetimes than default require admin privileges. |
| » usages | body | integer | false | Optional number of usages that this token can be used to generate a profile. Defaults to a single use if not provided. Specifying more than one usage requires admin privileges. |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | true | Specifies the connection profile type. |
| » username | body | [username](https://openvpn.net/as-docs/rest-api/#username) | false | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| » comment | body | string | false | Optional comment for the profile that will be stored with the token and applied when the profile is generated. |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Token URL generated successfully. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Token url could not be generated. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"lifetime": 1,
"usages": 1,
"profile_type": "autologin",
"username": "niccolo@paganini.it",
"comment": "connected from my iPhone"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### enumerateTokenIds
`GET /token-url/list`
Returns all currently valid profile token URLs known to the server. This endpoint does not support filtering and always returns the complete list of active token entries.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | List of all valid profile token URLs. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » profileTokens | \[[profileToken](https://openvpn.net/as-docs/rest-api/#profiletoken-1)\] | false | none | \[A token (typically one-time use) that can be used to retrieve a connection profile from Access Server. Access Server\] |
| »» token | string | false | none | the unique string that identifies the token |
| »» username | string | false | none | the username this token will generate the profile for |
| »» expires | string(date-time) | false | none | the token is only valid until this time |
| »» profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | false | none | Specifies the connection profile type. |
| »» usages | integer | false | none | how often this token can be used to retrieve a profile |
| »» comment | string | false | none | optional comment that will be applied to the profile when generated using this token |
###### Enumerated Values
| Property | Value |
| --- | --- |
| profile\_type | autologin |
| profile\_type | userlogin |
| profile\_type | generic |
| profile\_type | epki-generic |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"profileTokens": [
{
"token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
"username": "arne@openvpn.net",
"expires": "2019-08-24T14:15:22Z",
"profile_type": "autologin",
"usages": 1,
"comment": "connected from my iPhone"
}
]
}
```
#### deleteProfileSerial
`POST /profiles/delete/{serial}`
Delete a specific profile by its serial number identifier.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| serial | path | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial) | true | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Profiles were successfully deleted. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The profile could not be deleted. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | string | false | none | describes status of deletion |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete/{serial}',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": "string"
}
```
#### deleteProfileUser
`POST /profiles/delete-user`
##### Body parameter
```json
{
"users": [
"niccolo@paganini.it"
],
"filter": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » users | body | \[[username](https://openvpn.net/as-docs/rest-api/#username)\] | false | user name list whose connection profiles will be deleted. |
| » filter | body | string | false | will delete all profiles that have the argument as a substring |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Profiles were successfully deleted. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The user profiles were not deleted. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The user profiles were not found. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | string | false | none | describes status of deletion |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"users": [
"niccolo@paganini.it"
],
"filter": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete-user',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": "string"
}
```
#### deleteProfile
`POST /profiles/delete`
Delete one or more profiles by providing their serial numbers.
##### Body parameter
```json
[
"1708464983752887'"
]
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial) | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The request was successfully executed. The status for each profile is included in the response. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | could not delete the profile | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | any | false | none | describes status of deletion |
| » response | object | true | none | hash map that maps the requested delete request to a result |
| »» **additionalProperties** | [profileDeleteCode](https://openvpn.net/as-docs/rest-api/#profiledeletecode) | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **additionalProperties** | {“204”:null,“description”:“profile successfully deleted”} |
| **additionalProperties** | {“404”:null,“description”:“profile to be deleted was not found”} |
| **additionalProperties** | {“403”:null,“description”:“profile to be deleted is not owned by the user or another error”} |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '[
"1708464983752887'"
]';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": null,
"response": {
"21": 204,
"7127317": 404
}
}
```
### vpnca
Endpoints for managing the certificate authorities (CAs) used to sign VPN server and client certificates.
#### getVPNCas
`GET /ca/vpn/list`
Retrieve a list of all CAs used for VPN server and client certificates.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The request was successful. The response includes an array of CAs with details. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[allOf\] | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails) | false | none | none |
| »» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial)(int64) | true | none | A string representing the certificate serial number. A string is used instead of an integer to avoid issues with large values in JavaScript, which cannot reliably handle integers larger than 52 bits. |
| »» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname) | true | none | The certificate common name (CN). |
| »» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm) | true | none | Specifies the algorithm used for private/public key pair in an X.509 certificate. This is an identifier such as ecp384r1, secp256r1, or secp512r1. For algorithms with variable key lengths, the length is included in the name (e.g., rsa3072). |
| »» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
| »» cert\_type | [certificateType](https://openvpn.net/as-docs/rest-api/#certificatetype) | true | none | The type of certificate. |
| »» client\_profiles | integer | true | none | the number of VPN client profiles are issued by this CA. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| cert\_type | ca |
| cert\_type | old\_ca |
| cert\_type | cross\_ca |
| cert\_type | client |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"cert_type": "ca",
"client_profiles": 0
}
]
```
#### addCaGeneration
`POST /ca/vpn/create`
Create a new CA for VPN server and client certificates. This will also automatically generate the necessary cross-signed certificates.
##### Body parameter
```json
{
"algorithm": "secp384r1",
"common_name": "my shiny new CA"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [certificateRequest](https://openvpn.net/as-docs/rest-api/#certificaterequest) | false | none |
| » algorithm | body | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm) | false | Specifies the algorithm used for private/public key pair in an X.509 certificate. This is an identifier such as ecp384r1, secp256r1, or secp512r1. For algorithms with variable key lengths, the length is included in the name (e.g., rsa3072). |
| » common\_name | body | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname) | false | The certificate common name (CN). |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | The new CA was successfully created | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The request was invalid. | |
| This may occur if the selected algorithm is not allowed, the common name is too long, contains invalid characters, or already exists. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) | | |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"algorithm": "secp384r1",
"common_name": "my shiny new CA"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### delete\_**ca\_vpn**{serial}
`DELETE /ca/vpn/{serial}`
Delete a VPN certificate authority (CA) by serial number. If the CA still has client certificates, deletion will fail unless the `delete_clients` parameter is set to true.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The CA was successfully deleted | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The CA could not be deleted. | |
| This may occur if the CA still has client certificates or if it is the only CA in the system. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) | | |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The specified CA was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/{serial}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| serial | path | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1) | true | none |
| delete\_clients | query | boolean | false | will force the deletion of the CA (and all client certificates) |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### CaSupportedAlgorithms
`GET /ca/allowed-algorithms/list`
Retrieve a list of supported cryptographic private/public key algorithms that can be used to generate new certificates and certificate authorities (CA).
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns a list of allowed public/private key algorithms. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[[certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm)\] | false | none | \[Specifies the algorithm used for private/public key pair in an X.509 certificate. This is an identifier such as ecp384r1, secp256r1, or secp512r1. For algorithms with variable key lengths, the length is included in the name (e.g., rsa3072).\] |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/allowed-algorithms/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
"rsa2048",
"rsa3072",
"rsa4096",
"ed448",
"brainpoolP384r1",
"brainpoolP512r1",
"secp2256k1",
"Ed25519"
]
```
### info
Endpoints for querying various aspects of the running server and its current status.
#### certificateInfo
`POST /certificate/info`
Parse a PEM-encoded certificate and return detailed information about its properties. This endpoint is restricted to admin users to prevent potential security issues with the backend's X.509 parser. Use this endpoint to inspect certificates used in configurations, such as SAML and web certificates.
##### Body parameter
```json
{
"certificate": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » certificate | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate)(pem) | false | A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`. |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns detailed information about the X509 certificate. | [certificateInformationDetails](https://openvpn.net/as-docs/rest-api/#certificateinformationdetails) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The provided certificate could not be parsed, or encountered other problems. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"certificate": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/info',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"sha256fp": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"subj_alt_names": [
"DNS:foo.example.com",
"DNS:www.openvpn.net",
"IP:1.2.3.4"
],
"subject": [
"C=US",
"ST=Maryland",
"L=Pasadena",
"O=DevOrg",
"OU=FreeSoft",
"OU=non-free soft",
"CN=rogue software department"
],
"issuer": [
"C=US",
"ST=Maryland",
"L=Pasadena",
"O=DevOrg",
"OU=FreeSoft",
"OU=non-free soft",
"CN=rogue software CA department"
],
"ca": true
}
```
#### checkPrivateKey
`POST /certificate/check-private-key`
Parse a PEM-encoded certificate and a private key, and verify if they match. Provide the private key directly using the `private_key` attribute, or as a reference to a configuration key with the `config_key` parameter.
##### Body parameter
```json
{
"certificate": "string",
"private_key_passphrase": "string",
"private_key": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Both the private key and certificate were successfully parsed. The response indicates whether the private key matches the certificate. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The certificate or private key could not be parsed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » status | boolean | false | none | true if the private key matches the certificate |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"certificate": "string",
"private_key_passphrase": "string",
"private_key": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/check-private-key',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"status": true
}
```
#### post\_\_certificate\_check-against-ca-roots
`POST /certificate/check-against-ca-roots`
Verify a certificate against a provided list of CA certificates. If no CA certificates are provided, the system uses a built-in collection of common CAs trusted by browsers and operating systems. It will assume that the certificate(s) in the parameter `chain` are part of the required certificate chain. The function will first check that certificate and chain build a chain by checking if each certificates in chain signs the previous and then ultimately if the last certificate or second-to-last certificate of the chain is signed by one of the CAs in `ca_roots`. This checking both the last and second-to-last certificate is done since ca chains that are provided very commonly contains the CA itself or lack it. Note this function **only** establishes if there is a path that lead from the certificate to one of the root CAs. It does not check any other requirement that certificate typically have to considered valid. This includes but is not limited to checking if the certificates in the chain are intermediate CAs that are actually allowed to sign certificates, the keyUsage and extendedKeyUsage of the involved certificates or revocation. If the certificate contains multiple certificate the first certificate is considered to be the certificate to be checked and the other ones are considered to be intermediate certificates of the certificate chain and are treated the same way as the certificate(s) in the chain property.
##### Body parameter
```json
{
"certificate": "string",
"chain": "string",
"ca_roots": [
"string"
]
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The certificate has been successfully verified against the provided CA certificates. The response contains the trust chain that was found. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The certificate failed verification. Details are provided in the response. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const inputBody = '{
"certificate": "string",
"chain": "string",
"ca_roots": [
"string"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/check-against-ca-roots',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"chain": [
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"sha256fp": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"subj_alt_names": [],
"subject": [],
"issuer": [],
"ca": true
}
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » certificate | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate)(pem) | true | A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`. |
| » chain | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate)(pem) | false | A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`. |
| » ca\_roots | body | \[[pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate)\] | false | a list of CA certificates that should be used as trusted certificate authorities. If left empty AS will use the system certificates root CAs. This are very similar but not always identical to a browser trust store. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » chain | \[allOf\] | false | none | \[Provides more information about a certificate.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails) | false | none | none |
| »»» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial)(int64) | true | none | A string representing the certificate serial number. A string is used instead of an integer to avoid issues with large values in JavaScript, which cannot reliably handle integers larger than 52 bits. |
| »»» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname) | true | none | The certificate common name (CN). |
| »»» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm) | true | none | Specifies the algorithm used for private/public key pair in an X.509 certificate. This is an identifier such as ecp384r1, secp256r1, or secp512r1. For algorithms with variable key lengths, the length is included in the name (e.g., rsa3072). |
| »»» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »»» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »»» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »»» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »»» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» sha256fp | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint)(sha256) | false | none | The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate. |
| »»» subj\_alt\_names | \[string\] | false | none | provides a list of the subjectAlternative attributes of the certificate |
| »»» subject | \[string\] | false | none | the full subject of the certificate and not only the CN |
| »»» issuer | \[string\] | false | none | the full subject of the issuer. Note that this field cannot be trusted without verifying the signature on the certificate itself. Using this field should come with extreme care. |
| »»» ca | boolean | false | none | Whether the certificate represents a certificate authority |
| »»» self\_signed | boolean | false | none | the signature of the certificate is valid against its own public key |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### get\_\_eula
`GET /eula`
Retrieve the current end-user license agreement (EULA) and the acceptance status for the user. The EULA is considered accepted if the `aui.eula_version` matches the `eula_version_as` returned by this endpoint.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns the current EULA, its version, and whether the user has accepted it. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/eula',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"eula": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
"eula_web": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
```
##### Response Schema
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### serverInterfaces
`GET /server/interfaces`
Retrieves a list of network interfaces on the server and their assigned IP addresses.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| no\_loopback | query | boolean | false | if true exclude loopback interfaces |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | A list of network interfaces and their assigned IP and IPv6 addresses. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[[serverInterface](https://openvpn.net/as-docs/rest-api/#serverinterface)\] | false | none | \[Describes a Linux network interface along with its associated primary networks.\] |
| » name | any | false | none | the name identifying the interface |
| » networks | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet)\] | false | none | IP addresses assigned to the interface |
| »» ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| »» netip | string | false | none | the network IP address. |
| »» prefix\_length | integer | false | none | length of the prefix in CIDR notation |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/interfaces',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
{
"name": "eth0",
"networks": [
{},
{},
{}
]
}
]
```
#### get\_\_server\_info
`GET /server/info`
Provides a summary of the runtime status of the Access Server instance, including version information, web components, OS details and system architecture.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns information about the running Access Server instance. | [serverInfo](https://openvpn.net/as-docs/rest-api/#serverinfo) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/info',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": "27",
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"system_cores": null,
"os_hostname": "access-server-os-hostname"
}
```
#### get\_\_server\_dns
`GET /server/dns`
Returns DNS servers configured on the host OS (the same that will be pushed to VPN clients)
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | DNS servers | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/dns',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
{
"ip_addr": "string",
"ipv6": true
}
]
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » ip\_addr | string | false | none | IP address of a DNS server |
| » ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 address |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### get\_\_vpn\_dco-module
`GET /vpn/dco-module`
Checks with the data-channel offload (DCO) kernel module is available and returns the installed module version, if present.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns the DCO module status and version. | [dcoModuleStatus](https://openvpn.net/as-docs/rest-api/#dcomodulestatus) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/dco-module',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"available": true,
"version": "0.2.20230323"
}
```
#### post\_\_helper\_status-overview
`POST /helper/status-overview`
Combines multiple API calls into a single request to provide a consolidated status overview. This response includes data from `/config-items/{configurationProfile}/list` for the active profile, `/server/info`, `/vpn/dco-module`, and the current EULA status, including the latest version and whether the user has accepted it.
##### Body parameter
```json
{
"names": [
"vpn.server.cipher"
]
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Consolidated status overview data. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Something went wrong | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const inputBody = '{
"names": [
"vpn.server.cipher"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/helper/status-overview',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"configuration_items": {
"total": 0,
"items": [
{}
]
},
"server_info": {
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": "27",
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"system_cores": null,
"os_hostname": "access-server-os-hostname"
},
"dco_module": {
"available": true,
"version": "0.2.20230323"
},
"eula_status": {
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » names | body | \[[configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey-1)\] | false | list of configuration items that should be retrieve from the active configuration |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » configuration\_items | object | false | none | Response from the /config/{activeprofile}/items part of the query |
| »» total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| »» items | \[allOf\] | false | none | \[Represents a single configuration item. Check the derived\_from field to see whether it’s user-set, default, or inherited.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | object | false | none | none |
| »»»» name | [configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey) | true | none | The configuration value's key. |
| »»»» derived\_from | [configurationValueSource](https://openvpn.net/as-docs/rest-api/#configurationvaluesource) | true | none | Indicates the source from which the current value was derived, such as default or user-set. |
| »»»» type | string | false | none | Determines the value type of this configuration item. This also implies which of the different value attributes are expected to be present on this configuration item. |
| »»»» description | string | false | none | A user readable description of the configuration item that gives a user an understandable. This item can be absent for custom configuration values. |
| »»»» category | string | true | none | Different items have different visibility/category that should be taken into account when presenting them to the user. This key informs the UI if a variable is deprecated but still evaluated (deprecated), deprecated and removed (removed), normal, advanced (a value that for normal operation of OpenVPN Access Server should need to be changed as it is typically reserved for some corner-case or speciality configurations) or is a calculated value that is readonly as it is calculated from other configuration items but is not modifiable by the user (derived). Items that have a type of required often do not have a default value but must be set in order for Access to correctly work (e.g. host.name). Removed values should be only shown by the UI if the are set by the user. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | any | false | none | none |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [integerConfigurationValue](https://openvpn.net/as-docs/rest-api/#integerconfigurationvalue) | false | none | A server configuration setting expressed as an integer. |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | object | false | none | none |
| »»»»»» value | integer | false | none | none |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | [integerConfigurationLimits](https://openvpn.net/as-docs/rest-api/#integerconfigurationlimits) | false | none | none |
| »»»»»» default\_value | integer | false | none | The default value for the configuration. |
| »»»»»» max\_value | integer | false | none | A hint of maximum allowed value |
| »»»»»» min\_value | integer | false | none | A hint for minimum allowed value |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [invalidIntegerConfigurationValue](https://openvpn.net/as-docs/rest-api/#invalidintegerconfigurationvalue) | false | none | A configuration value that is expressed as an integer. |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | [integerConfigurationLimits](https://openvpn.net/as-docs/rest-api/#integerconfigurationlimits) | false | none | none |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | object | false | none | none |
| »»»»»» value | string | false | none | none |
| »»»»»» invalid\_value | boolean | false | none | This is set to True to indicate that the value is invalid as integer. This happens if the value in the configuration database itself has an invalid value. The field value will in this case be a string. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [booleanConfigurationValue](https://openvpn.net/as-docs/rest-api/#booleanconfigurationvalue) | false | none | none |
| »»»»» value | boolean | false | none | none |
| »»»»» default\_value | boolean | false | none | The default value for the configuration. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [stringConfigurationValue](https://openvpn.net/as-docs/rest-api/#stringconfigurationvalue) | false | none | A server configuration setting expressed as a string. Only one of `value` or `redacted_value` will be present. |
| »»»»» value | string | false | none | the value of this string configuration |
| »»»»» redacted\_value | string | false | none | the real value of this configuration key is not present because it is a private key or password. The value of this string will give an indication of the redacted value. |
| »»»»» default\_value | string | false | none | The default value for the configuration. |
| »»»»» allowed\_values | \[string\] | false | none | if present this array has a list of the allowed values |
| »»»»» type\_hint | string | false | none | if present, this type hint denotes this configuration value to contain a special type of value, so the UI can do additional verification to ensure the user input matches this type |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [customConfigurationValue](https://openvpn.net/as-docs/rest-api/#customconfigurationvalue) | false | none | A configuration key unknown to the backend, possible user-defined or carried over from a new version during downgrade. |
| »»»»» value | string | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » server\_info | [serverInfo](https://openvpn.net/as-docs/rest-api/#serverinfo) | false | none | none |
| »» version | string | false | none | the version number of Access Server |
| »» build | string | false | none | the build of Access Server. |
| »» web\_version | string | false | none | the build version number of Access Server UI |
| »» web\_override | boolean | false | none | if true the version of the web ui that is used comes from an override-web.zip instead of the bundled version |
| »» client\_version | string,null | false | none | version of the embedded client package. `null` if the user manually deleted the files of the openvpn-as-bundled-clients package |
| »» os\_distribution | string | false | none | a human readable identifier of the current (Linux) distribution like PRETTY\_NAME from /etc/os-release |
| »» architecture | string | false | none | the CPU architecture |
| »» cores | integer | false | none | the number of cores available to OpenVPN Access server. Typically identical to system\_cores. |
| »» system\_cores | any | false | none | the number of cores visible to the operating system |
| »» os\_hostname | string | false | none | Operating system’s hostname |
| » dco\_module | [dcoModuleStatus](https://openvpn.net/as-docs/rest-api/#dcomodulestatus) | false | none | none |
| »» available | boolean | true | none | whether AS detected an installed and working data channel offloading kernel module |
| »» version | string | true | none | version of the module if available |
| » eula\_status | [eulaStatus](https://openvpn.net/as-docs/rest-api/#eulastatus) | false | none | none |
| »» eula\_version\_as | integer | false | none | The version of the AS EULA |
| »» eula\_web\_hash | string(sha256) | false | none | A SHA256 string in hex format without : separators |
| »» eula\_accepted | boolean | false | none | indicates whether the config setting (aui.eula\_version) has the same value as eula\_version\_as |
###### Enumerated Values
| Property | Value |
| --- | --- |
| derived\_from | default |
| derived\_from | local\_db |
| derived\_from | cluster\_db |
| derived\_from | mysql\_standalone\_db |
| derived\_from | as\_conf |
| derived\_from | environment |
| derived\_from | runtime |
| derived\_from | other |
| type | custom |
| type | integer |
| type | boolean |
| type | string |
| category | deprecated |
| category | removed |
| category | normal |
| category | required |
| category | derived |
| category | advanced |
| category | custom |
| type\_hint | ipv4Address |
| type\_hint | ipv6Address |
| type\_hint | ipAddress |
| type\_hint | hostname |
| type\_hint | pemCertificate |
| type\_hint | pemPrivateKey |
| architecture | arm64 |
| architecture | amd64 |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
### license
Endpoints for examining and setting licensing of the AS instance
#### licenseInfo
`GET /license/info`
Retrieves the current licensing status of the Access Server instance, including license type, active client connections, and fixed license details if applicable.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Licensing information for the Access Server instance. | [licenseInfo](https://openvpn.net/as-docs/rest-api/#licenseinfo-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/info',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"licensing_type": "unlicensed",
"current_cc": 3,
"max_cc": 13,
"fixed_licenses": [
{
"expiry": "2019-08-24T14:15:22Z",
"key": "string",
"max_cc": 0
}
]
}
```
#### checkSubscription
`POST /license/subscription/test`
Tests a provided license key against the subscription service and returns the results. This call does not configure Access Server to use the subscription. It only validates and retrieves subscription details.
##### Body parameter
```json
{
"subscription": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » subscription | body | string | true | The subscription file. This is either a string containing a json object or a base64 encoding of the json object. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Subscription test result returned successfully. | [subscriptionInfo](https://openvpn.net/as-docs/rest-api/#subscriptioninfo) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The license key format is invalid, or an error occurred while processing the test. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"subscription": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription/test',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"agent_id'": "13014502862141447248",
"agent_disabled": true,
"cc_limit": 13,
"error": "string",
"fallback_cc'": 2,
"grace_period": 30,
"last_successful_update": "2019-08-24T14:15:22Z",
"total_cc": 0,
"name": "Test subscription for development",
"subkey": "ASUYHgkSWvVQFZhJXVdgtEa_AStctYuHirYZeFbZjLvQCWCaViVamXwL_7a289be35f6987c9aec4585c922a740c1b7620d5",
"billing_id": "tctYuHirYZeFbZjLvQC",
"next_update": "2019-08-24T14:15:22Z",
"updates_failed": 0,
"notes": [
"Subscription will expire on 1/2/3",
"Maximum allowed concurrent connections might be limited to 23 by the 'subscription.local_cc_limit' setting"
],
"overdraft": true,
"server": "asb.sts.openvpn.net",
"type": "-",
"state": "'prop' { 'certfp': 'LfLIlGKsZds4940SOmsj5Q+xunxh21yx0+3DEXK2bB4=',\n - 'id': 'mynode.cloud.example.com',\n - 'ip': '178.203.239.243',\n - 'ip6': '2a02:908:2220:a200:5054:ff:fef2:d165',\n - 'oshost': 'noble-as' }\n",
"props": null
}
```
#### loadSubscription
`POST /license/subscription`
Instructs Access Server to use the provided license key for licensing. This call does not validate whether the subscription is correct or active. Use the `/license/subscription/test` endpoint to check validity before calling this one. Submitting a new subscription key with this endpoint will overwrite any existing subscription configuration.
##### Body parameter
```json
{
"subscription": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » subscription | body | string | true | The subscription file. This is either a string containing a json object or a base64 encoding of the json object. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Subscription has been successfully loaded. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The license key format is invalid, or an error occurred while applying the subscription. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"subscription": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### deactivateSubscription
`DELETE /license/subscription`
Removes the currently active subscription configuration from the OpenVPN Access Server instance.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Subscription has been successfully deactivated. | None |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### activateFixedLicenseOnline
`POST /license/fixed-license/online-activation`
Activates a fixed license key for Access Server by validating the license key with the online licensing service.
##### Body parameter
```json
{
"license": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » license | body | string | true | The license file |
###### The license format is invalid, or an error occurred during activation.
```json
{
"message": "License not found on server"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Fixed license key successfully activated. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The license format is invalid, or an error occurred during activation. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 503 | [Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4) | License server is unreachable. | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"license": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/fixed-license/online-activation',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### activateFixedLicenseOffline
`POST /license/fixed-license/offline-activation`
Activates a fixed license key for Access Server using an uploaded license file. The license file is validated during this process.
##### Body parameter
```yaml
license: string
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » license | body | string | true | The license file |
###### The license format is invalid, or an error occurred during activation.
```json
{
"message": "Fixed license already expired"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Fixed license key has been successfully activated. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The license format is invalid, or an error occurred during activation. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"license": "string"
}';
const headers = {
'Content-Type':'multipart/form-data',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/fixed-license/offline-activation',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### licenseGetMachineId
`GET /license/machine-id`
Returns the machine ID file used for licensing purposes in Access Server.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Machine ID file returned successfully. | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'text/plain',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/machine-id',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```
"string"
```
### proxy
A pseudo-endpoint that explains the proxying mechanism used to route API requests to other OpenVPN Access Server backend nodes in a clustered setup.
#### post\_\_proxy
`POST /proxy`
This is not a real API endpoint, but a documentation placeholder to explain the proxy mechanism used by OpenVPN Access Server in a clustered setup.
Most API endpoints in Access Server support proxying requests to other backend nodes in the cluster. When a request includes the `X-OpenVPN-AS-Node` header, the middleware checks if the specified node name matches a known backend server. See the `/cluster/nodes/list` endpoint for retrieving all backend servers. If it matches, the request is proxied to that node, and the response is forwarded back to the client.
The proxied request will include:
- X-Forwarded-For: The original client’s IP address.
- X-Forwarded-Host: The node name that forwarded the request.
If a node receives a request where its own name appears in the `X-Forwarded-Host` header, this indicates a loop (typically caused by incorrect DNS or cluster configuration). In such cases, the request fails with an error.
Authentication and validation are not performed by the proxy. The middleware only ensures the target is a valid backend server. Responses described here may occur in addition to standard endpoint responses when proxying is in use.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 502 | [Bad Gateway](https://tools.ietf.org/html/rfc7231#section-6.6.3) | Communication problem with the target backend node (other than a timeout) or the X-OpenVPN-AS-Node is not in the list of backend servers. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 504 | [Gateway Time-out](https://tools.ietf.org/html/rfc7231#section-6.6.5) | Proxying the request to the target node timed out. | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-AS-Node':'string',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/proxy',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| X-OpenVPN-AS-Node | header | string | false | Optional header used to determine which backend node the request should be forwarded to. |
###### Detailed descriptions
**X-OpenVPN-AS-Node**: Optional header used to determine which backend node the request should be forwarded to. The value must match the node name, not the node `api_endpoint`. See the /proxy pseudo-endpoint for a description of the proxying mechanism.
### cluster
Endpoints for configuring, monitoring, and managing an Access Server cluster, including node setup and status checks.
#### clusterListNodes
`GET /cluster/nodes/list`
Returns a list of all nodes in the cluster, including metadata. Allows identifying backend nodes in a clustered Access Server setup.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | List of cluster nodes. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » nodes | object | false | none | holds a dictionary of all the nodes that are part of the cluster |
| »» **additionalProperties** | any | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [clusterNode](https://openvpn.net/as-docs/rest-api/#clusternode) | false | none | Describes a node in the cluster. The certificate field represents the certificate the node presents on its api\_endpoint and is used to verify the node's identity. |
| »»»» name | string | true | none | the name that uniquely identifies the cluster node \[node\_name\] |
| »»»» api\_endpoint | [apiEndpoint](https://openvpn.net/as-docs/rest-api/#apiendpoint) | false | none | The API endpoint used to communicate with a specific node. Must be in the format https://ip-or-hostname:port. The https scheme is required because the certificateFingerprint is used by the HTTPS client to verify the identity of the node. |
| »»»» certificate\_fingerprint | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint)(sha256) | false | none | The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | object | false | none | none |
| »»»» restart\_pending | boolean | false | none | Indicates if a node has a pending restart. |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/nodes/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"nodes": {
"property1": {
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"restart_pending": true
},
"property2": {
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"restart_pending": true
}
}
}
```
#### rrdnshostname
`PUT /cluster/rr-dns-hostname`
Sets the `host.name` value in the local configuration database (confdb\_local) on all nodes in the cluster, using the `rr_dns_hostname` value from the cluster database. Ensures consistent DNS naming across a clustered Access Server deployment.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The cluster DNS hostname was updated successfully on all nodes. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Failed to update the cluster DNS hostname due to a configuration error. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/rr-dns-hostname',
{
method: 'PUT',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### clustergetprops
`GET /cluster/props`
Retrieves cluster properties from the cluster database (ClusterDB), such as round-robin DNS hostname and related settings.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successfully retrieved cluster properties from the cluster | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Getting the cluster properties failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » props | object | false | none | holds a dictionary of all props of the cluster |
| »» **additionalProperties** | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops) | false | none | Properties shared across all nodes in an Access Server cluster. |
| »»» rr\_dns\_hostname | string | false | none | the Round-Robin hostname that uniquely identifies the cluster |
| »»» rr\_dns\_new\_nodes | boolean | false | none | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/props',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"props": {
"property1": {
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
},
"property2": {
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
}
}
```
#### clustersetprops
`POST /cluster/props`
Sets cluster properties, such as the round-robin DNS hostname, in the cluster database (ClusterDB).
##### Body parameter
```json
{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops) | false | none |
| » rr\_dns\_hostname | body | string | false | the Round-Robin hostname that uniquely identifies the cluster |
| » rr\_dns\_new\_nodes | body | boolean | false | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
###### Setting the cluster properties failed.
```json
{
"message": "rr_dns_hostname has invalid characters in it"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The cluster properties were successfully updated in the database. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Setting the cluster properties failed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/props',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### post\_\_cluster\_join
`POST /cluster/join`
Joins a standalone Access Server instance to an existing cluster. If the certificate\_fingerprint is not provided, it is automatically calculated by the joining node. The cluster must already be set up.
##### Body parameter
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The server successfully joined the cluster. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The server failed to join the cluster. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/join',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterNodeJoinRequest](https://openvpn.net/as-docs/rest-api/#clusternodejoinrequest-1) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### post\_\_cluster\_create
`POST /cluster/create`
Creates a new cluster using the current server configuration as the foundation for the shared cluster database. The current node becomes a member of the newly created cluster.
##### Body parameter
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
},
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The cluster was created and the current node joined successfully. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The cluster could not be created. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
},
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterNodeCreateRequest](https://openvpn.net/as-docs/rest-api/#clusternodecreaterequest-1) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### post\_\_cluster\_leave
`POST /cluster/leave`
Removes the current node from the cluster.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The node was successfully removed from the cluster. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The request to leave the cluster failed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/leave',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### put\_\_database\_convert
`PUT /database/convert`
Converts local SQLite databases to MySQL and updates the configuration file (as.conf).
Requires a full Access Server restart for changes to take effect.
##### Body parameter
```json
{
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The database was successfully converted, and the configuration updated. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The database conversion failed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/database/convert',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [mysqlUriParts](https://openvpn.net/as-docs/rest-api/#mysqluriparts) | false | none |
| » host | body | string | true | none |
| » port | body | integer | true | none |
| » username | body | string | true | none |
| » password | body | string | true | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
### maintenance
Endpoints for performing server maintenance tasks, such as restarting Access Server or its services.
#### get\_\_support\_report
`GET /support/report`
Generates a support report for Access Server, containing commonly requested diagnostic information to assist with troubleshooting.
This operating is resource-intensive, as it executes external programs to gather system data, and may take some time to complete. Use this endpoint only when necessary.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Support report generated successfully. The output is the same as running `sacli support`. | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'text/plain',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/support/report',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```
"string"
```
#### post\_\_server\_restart
`POST /server/restart`
instructs the backend to be restarted
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Server restart successfully scheduled | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Server has some misconfiguration and restart is not scheduled | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/restart',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| restartMode | query | [restartMode](https://openvpn.net/as-docs/rest-api/#restartmode) | false | none |
| group | query | string | false | for the warm restart mode, this limits the services to the listed groups to be restarted |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| restartMode | cold |
| restartMode | warm |
| restartMode | dry\_run |
| restartMode | systemctl |
| restartMode | server\_agent |
#### serverStatus
`GET /server/status`
Retrieves the current status of the server and its individual services. The output is similar to the result of running `sacli Status`, which shows the status of the internal Access Server service.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Server and status returned successfully | [serverStatus](https://openvpn.net/as-docs/rest-api/#serverstatus-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"last_restarted": "2019-08-24T14:15:22Z",
"service_status": {
"property1": {
"status": "on",
"error": []
},
"property2": {
"status": "on",
"error": []
}
},
"auth_module_status": {
"property1": "on",
"property2": "on"
}
}
```
### configurationProfile
API to manage Access Server main configuration database. These endpoints allow you to retrieve, update, and manage configuration values stored in the active or named configuration profiles.
#### enumerateConfigurationProfileList
`GET /config-profile/list`
Returns the name of the currently active configuration profile and a list of all available profiles.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | A list of all configuration profiles on Access Server | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » active\_profile | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | false | none | The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups. |
| » profiles | \[[configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1)\] | false | none | A list of all configuration profiles on Access Server |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"active_profile": "default",
"profiles": [
"default",
"heaven",
"hades",
"olymp"
]
}
```
#### configurationProfileDelete
`DELETE /config-profile/{profile}`
Deletes a configuration profile if it exists and is not currently active.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | true | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | Configuration profile was successfully deleted | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | profile deletion would violate some constraints like deleting the active profile | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Specified configuration profile was not found. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### configurationProfileCreate
`POST /config-profile`
Creates a new configuration profile, optionally coppying the initial values from an other profile if the `copyFrom` parameter is present. Otherwise the new configuration profile will be empty.
##### Body parameter
```json
{
"profile": "string",
"copy_from": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | true | none |
| » profile | body | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | true | The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups. |
| » copy\_from | body | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | false | The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | The configuration profile was created successfully. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The profile name is invalid, or another error occurred during creation. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The specified `copy_from` configuration profile does not exist. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"profile": "string",
"copy_from": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### validateConfigProfile
`GET /config-profile/{profile}/validate`
Validates the specified configuration profile and returns any detected errors.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | true | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The configuration profile is valid with no detected errors. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The profile contains validation issues. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Configuration profile does not exist. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}/validate',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### RunSetActiveProfile
`POST /config-profile/{profile}/set-active`
Validates the specified configuration profile and, if valid, sets it as the active profile and restarts OpenVPN Access Server using the selected restart mode.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | true | The name of the profile to activate. |
| restartMode | query | [restartMode](https://openvpn.net/as-docs/rest-api/#restartmode) | false | The restart mode that should be used to restart the server. |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| restartMode | cold |
| restartMode | warm |
| restartMode | dry\_run |
| restartMode | systemctl |
| restartMode | server\_agent |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success. No errors in the profile are detected and the new profile is being set. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | validation of the profile encountered some problems or some other error occurred. See error reason for more details. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | the requested configuration profile was not found. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}/set-active',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### getConfigItems
`POST /config-items/{configurationProfile}/list`
fetches a list of specified configuration values or all if names is not given. The total amount for all item is limited by the number of available configuration options (\<500) in Access Server, so no pagination is provided in this API.
##### Body parameter
```json
{
"names": [
"vpn.server.cipher"
],
"include_pattern_keys": false
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| configurationProfile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-1) | true | The name of the configuration profile to list items from. |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The list of configuration items was successfully returned. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Configuration profile does not exist. | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail) |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| » items | \[allOf\] | false | none | \[Represents a single configuration item. Check the derived\_from field to see whether it’s user-set, default, or inherited.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey) | true | none | The configuration value's key. |
| »»» derived\_from | [configurationValueSource](https://openvpn.net/as-docs/rest-api/#configurationvaluesource) | true | none | Indicates the source from which the current value was derived, such as default or user-set. |
| »»» type | string | false | none | Determines the value type of this configuration item. This also implies which of the different value attributes are expected to be present on this configuration item. |
| »»» description | string | false | none | A user readable description of the configuration item that gives a user an understandable. This item can be absent for custom configuration values. |
| »»» category | string | true | none | Different items have different visibility/category that should be taken into account when presenting them to the user. This key informs the UI if a variable is deprecated but still evaluated (deprecated), deprecated and removed (removed), normal, advanced (a value that for normal operation of OpenVPN Access Server should need to be changed as it is typically reserved for some corner-case or speciality configurations) or is a calculated value that is readonly as it is calculated from other configuration items but is not modifiable by the user (derived). Items that have a type of required often do not have a default value but must be set in order for Access to correctly work (e.g. host.name). Removed values should be only shown by the UI if the are set by the user. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | any | false | none | none |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [integerConfigurationValue](https://openvpn.net/as-docs/rest-api/#integerconfigurationvalue) | false | none | A server configuration setting expressed as an integer. |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | object | false | none | none |
| »»»»» value | integer | false | none | none |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [integerConfigurationLimits](https://openvpn.net/as-docs/rest-api/#integerconfigurationlimits) | false | none | none |
| »»»»» default\_value | integer | false | none | The default value for the configuration. |
| »»»»» max\_value | integer | false | none | A hint of maximum allowed value |
| »»»»» min\_value | integer | false | none | A hint for minimum allowed value |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [invalidIntegerConfigurationValue](https://openvpn.net/as-docs/rest-api/#invalidintegerconfigurationvalue) | false | none | A configuration value that is expressed as an integer. |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [integerConfigurationLimits](https://openvpn.net/as-docs/rest-api/#integerconfigurationlimits) | false | none | none |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | object | false | none | none |
| »»»»» value | string | false | none | none |
| »»»»» invalid\_value | boolean | false | none | This is set to True to indicate that the value is invalid as integer. This happens if the value in the configuration database itself has an invalid value. The field value will in this case be a string. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [booleanConfigurationValue](https://openvpn.net/as-docs/rest-api/#booleanconfigurationvalue) | false | none | none |
| »»»» value | boolean | false | none | none |
| »»»» default\_value | boolean | false | none | The default value for the configuration. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [stringConfigurationValue](https://openvpn.net/as-docs/rest-api/#stringconfigurationvalue) | false | none | A server configuration setting expressed as a string. Only one of `value` or `redacted_value` will be present. |
| »»»» value | string | false | none | the value of this string configuration |
| »»»» redacted\_value | string | false | none | the real value of this configuration key is not present because it is a private key or password. The value of this string will give an indication of the redacted value. |
| »»»» default\_value | string | false | none | The default value for the configuration. |
| »»»» allowed\_values | \[string\] | false | none | if present this array has a list of the allowed values |
| »»»» type\_hint | string | false | none | if present, this type hint denotes this configuration value to contain a special type of value, so the UI can do additional verification to ensure the user input matches this type |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [customConfigurationValue](https://openvpn.net/as-docs/rest-api/#customconfigurationvalue) | false | none | A configuration key unknown to the backend, possible user-defined or carried over from a new version during downgrade. |
| »»»» value | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| derived\_from | default |
| derived\_from | local\_db |
| derived\_from | cluster\_db |
| derived\_from | mysql\_standalone\_db |
| derived\_from | as\_conf |
| derived\_from | environment |
| derived\_from | runtime |
| derived\_from | other |
| type | custom |
| type | integer |
| type | boolean |
| type | string |
| category | deprecated |
| category | removed |
| category | normal |
| category | required |
| category | derived |
| category | advanced |
| category | custom |
| type\_hint | ipv4Address |
| type\_hint | ipv6Address |
| type\_hint | ipAddress |
| type\_hint | hostname |
| type\_hint | pemCertificate |
| type\_hint | pemPrivateKey |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"names": [
"vpn.server.cipher"
],
"include_pattern_keys": false
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-items/{configurationProfile}/list',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"total": 0,
"items": [
{
"name": "vpn.server.cipher",
"derived_from": "default",
"type": "custom",
"description": "string",
"category": "deprecated",
"value": 0,
"default_value": 0,
"max_value": 0,
"min_value": 0
}
]
}
```
#### post\_**config-items**{configurationProfile}
`POST /config-items/{configurationProfile}`
Sets or updates configuration items for the specified profile.
This is an atomic operation: all changes must succeed or none will be applied. Setting a value to null deletes it, reverting to the default value.
##### Body parameter
```json
{
"property1": "string",
"property2": "string"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Configuration items were updated successfully. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | One or more configuration values are invalid; no changes were made. | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Configuration profile does not exist. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"property1": "string",
"property2": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-items/{configurationProfile}',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "config values had errors",
"detail": {
"host.name": "Contains invalid character %",
"server.port": "Must be an integer between 1 and 65335"
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| configurationProfile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
| body | body | object | true | none |
| » **additionalProperties** | body | string | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
### saml
Endpoints for managing SAML-based authentication flow.
#### post\_\_saml\_acs
`POST /saml/acs`
Completes the SAML authentication process by accepting a SAML assertion from the Identity Provider (IdP).
After a successful login at the IdP, the IdP redirects to the /saml/acs URL of the Access Server with the assertion. This endpoint processes the assertion to complete the login flow.
##### Body parameter
```yaml
RelayState: string
SAMLResponse: string
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns an HTML page (similar to index.html) that includes a JavaScript block assigning the SAML assertion to a `SAMLResponse` variable and the RelayState to a `RelayState` variable. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Returned when the request is invalid or the assertion cannot be validated. | None |
| 405 | [Method Not Allowed](https://tools.ietf.org/html/rfc7231#section-6.5.5) | Only POST requests are allowed at this endpoint. | None |
```javascript
const inputBody = '{
"RelayState": "string",
"SAMLResponse": "string"
}';
const headers = {
'Content-Type':'application/x-www-form-urlencoded',
'Accept':'text/html'
};
fetch('/api/saml/acs',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » RelayState | body | string | false | cws, profile or vpnauthnodeidsessionid |
| » SAMLResponse | body | string(xml string encoded in base64 format) | true | none |
###### Returns an HTML page (similar to index.html) that includes a JavaScript block assigning the SAML assertion to a `SAMLResponse` variable and the RelayState to a `RelayState` variable.
```
"< SAMLResponse = \"[samlassertion data]\"; RelayState = \"cwslogin\"; [content of index.html]"
```
###### Returned when the request is invalid or the assertion cannot be validated.
```
"< HEAD content SAML authentication failed
assertion request is invalid
"
```
###### Only POST requests are allowed at this endpoint.
```
"< HEAD content SAML authentication failed
assertion method is not supported
"
```
##### Response Schema
This operation does not require authentication
#### get\_\_saml\_metadata
`GET /saml/metadata`
Returns the SAML Service Provider metadata in XML format.
This URL can be used by the IdP during the SAML authentication setup process.
##### SAML is not configured, or the configuration is invalid.
```
"< HEAD content 404 Not Found
SAML not configured or invalid configuration
"
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns the XML metadata for the Access Server SAML Service Provider. | string |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | SAML is not configured, or the configuration is invalid. | None |
```javascript
const headers = {
'Accept':'application/samlmetadata+xml',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/saml/metadata',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Response Schema
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### get\_\_saml\_redirect
`GET /saml/redirect`
Used during the VPN session authentication to redirect to the SAML IdP when the URL is too long to transmit directly via the VPN protocol.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Redirects the client to the SAML IdP URL. | None |
This operation does not require authentication
```javascript
fetch('/api/saml/redirect',
{
method: 'GET'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### get\_\_auth\_get-idp-url
`GET /auth/get-idp-url`
Returns the IdP URL for redirecting the user and initiating SAML authentication.
If `relay_state` is not provided, it defaults to `cws`.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns the IdP URL to redirect the user for SAML authentication. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | RelayState invalid or SAML configuration error. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const headers = {
'Accept':'string'
};
fetch('/api/auth/get-idp-url',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| relay\_state | query | string | false | If not set, the relay\_state is assumed to be `cws`. |
### vpn
Endpoints directly related to connected VPN users, including status queries and client session control.
#### vpnAuthSAMLAssertion
`POST /auth/vpn/vpnsaml`
Forwards a SAML assertion and relay state to the VPN authentication mechanism. This is typically used by the UI to forward an assertion when the relay state starts with `vpnauth~`.
##### Body parameter
```json
{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The SAML assertion was forwarded successfully. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The assertion was invalid, such as an empty string or a malformed request. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | The relay state is incorrect, or the assertion was rejected. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/vpn/vpnsaml',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### get\_\_vpn\_status
`GET /vpn/status`
Retrieves the OpenVPN server status, including currently connected clients and information about the OpenVPN daemon(s). This endpoint always returns the full dataset for all VPN clients and daemons. Pagination is not supported, as limiting the response would require dropping already retrieved information, with minimal benefit in reduced data transfer.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Returns the VPN server status and client connection details. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"vpn_clients": [
{
"daemon_id": "openvpn_7",
"client_id": 7,
"bytes_sent": 0,
"bytes_received": 0,
"commonname": "plato_AUTOLOGIN",
"username": "plato",
"connected_since": "2019-08-24T14:15:22Z",
"datachannel_cipher": "ChaCha20-Poly1305",
"real_address": "1.2.7.8:23123",
"virtual_ipv4_address": "10.0.0.7",
"virtual_ipv6_address": "fd00:f00f::b00f"
}
],
"vpn_daemons": {
"property1": {
"dco": true,
"version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
},
"property2": {
"dco": true,
"version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
}
}
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » vpn\_clients | \[allOf\] | false | none | List of connected VPN clients |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [vpnConnectionID](https://openvpn.net/as-docs/rest-api/#vpnconnectionid) | false | none | none |
| »»» daemon\_id | [daemonID](https://openvpn.net/as-docs/rest-api/#daemonid) | true | none | An ID that identifies the specific OpenVPN daemon the client is connected to. |
| »»» client\_id | [clientID](https://openvpn.net/as-docs/rest-api/#clientid) | true | none | The client ID of the connected client. This ID is only unique for a specific daemonID. In other words, only the combination of daemonID and clientID uniquely identifies a client. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» bytes\_sent | integer | false | none | number of bytes sent |
| »»» bytes\_received | integer | false | none | number of bytes received |
| »»» commonname | string | false | none | the common name the client uses in its certificate. |
| »»» username | string | false | none | username of the client |
| »»» connected\_since | string(date-time) | false | none | time in UTC since when the client is connected. |
| »»» datachannel\_cipher | string | false | none | the data channel cipher that is used with this client. |
| »»» real\_address | string | false | none | the IP address the client is connected from |
| »»» virtual\_ipv4\_address | string | false | none | the virtual or VPN address of the client |
| »»» virtual\_ipv6\_address | string | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » vpn\_daemons | object | false | none | none |
| »» **additionalProperties** | [vpnDaemonStatus](https://openvpn.net/as-docs/rest-api/#vpndaemonstatus) | false | none | The current status of a VPN daemon. |
| »»» dco | boolean | false | none | if DCO is used on this daemon instance |
| »»» version | string | false | none | the OpenVPN 2.x version of the daemon |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### disconnectClient
`POST /vpn/client/disconnect`
Disconnects one or more VPN clients from the server. Either `users` or `clients` must be provided in the request body.
##### Body parameter
```json
{
"reason": "John should not be working after hours",
"client_reason": "Client disconnected for administrative reasons",
"users": [
"niccolo@paganini.it"
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The specified client(s) were disconnected successfully. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The specified client could not be found by daemon and client ID. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"reason": "John should not be working after hours",
"client_reason": "Client disconnected for administrative reasons",
"users": [
"niccolo@paganini.it"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/client/disconnect',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
### cws
CWS stands for Client Web Service. These endpoints are used by normal (non-admin) users to interact with Access Server, such as managing sessions or profiles. Some endpoints support optional admin-level functionality, like acting on behalf of another user.
#### generateInstallerUrl
`POST /installer-url`
##### Body parameter
```json
{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [installerProfileRequest](https://openvpn.net/as-docs/rest-api/#installerprofilerequest) | false | none |
| » user | body | [username](https://openvpn.net/as-docs/rest-api/#username) | false | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| » installer\_type | body | [installerType](https://openvpn.net/as-docs/rest-api/#installertype) | true | Specifies the type of the installer binary to be generated. |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | false | Specifies the connection profile type. |
| » tls\_crypt\_v2 | body | boolean | false | The client is capable of TLS-Crypt v2 |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » installer\_type | win\_v3 |
| » installer\_type | mac\_v3 |
| » installer\_type | win |
| » installer\_type | mac |
| » installer\_type | ios |
| » installer\_type | android |
| » installer\_type | linux |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Installer URL was successfully generated. | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Returned if the installer URL generation failed. | |
| This can happen if the generation of the URL is not permitted, the requested installer is not downloadable, or if the server cannot locate the required OpenVPN Connect installer file. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) | | |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/installer-url',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
### userprop
Endpoints for retrieving and modifying user properties stored in Access Server.
#### getdefaultuserprops
`GET /users/defaultuser`
Retrieves the special meta user, called `__DEFAULT__`, defining defaults for users.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successfully retrieved the default user configuration. | [userPropUserDefault](https://openvpn.net/as-docs/rest-api/#userpropuserdefault) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/users/defaultuser',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"name": "string",
"deny": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"deny_web": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"admin": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"autologin": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"auth_method": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cc_commands": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"totp": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"password_strength": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"allow_password_change": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"reroute_gw": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"allow_generate_profiles": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"bypass_subnets": [
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false
}
],
"def_deny": true,
"cli_script_connect_win_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"property2": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
}
},
"group": "stringsection"
}
```
#### getuserprops
`POST /users/list`
Retrieves a list of user profiles, excluding the default user (“type”: “user\_default”); use `/users/defaultuser` to fetch the default user.
##### Body parameter
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "admin",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"group": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"users": [
"niccolo@paganini.it"
],
"proplist": [
"string"
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [userRequestParameters](https://openvpn.net/as-docs/rest-api/#userrequestparameters) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successfully returned user profiles. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Only admin users are allowed to use this API endpoint. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of users that match if pagination is not in effect, this matches the size of the provided array |
| » profiles | \[allOf\] | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userProp](https://openvpn.net/as-docs/rest-api/#userprop-1) | false | none | This hold the attributes of the userprop that is not specifically handled in a special way like passwords or group members. OpenAPI does not allow to specify description along with $ref so the description for the individual keys is in this descriptions. - deny (boolean): If true cannot connect or login (prop\_deny) - deny\_web (boolean): If true cannot login to web (prop\_deny\_web) - admin (boolean): user is admin (prop\_superuser) - autologin (boolean): autologin profile generation is allowed by the user themselves (prop\_autologin) - auth\_method (string): the authentication method that will be used for the user. Maps to user\_auth\_type and default configuration etc. - cc\_commands: custom OpenVPN directives that will imported for the user on the server side (prop\_cc\_cmds) - totp: specifies whether TOTP based MFA is required (prop\_google\_auth) - password\_strength: password strength check is enforced when changing the password for local auth (prop\_pwd\_strength/cs.cws.pwd\_strength) - allow\_password\_change (boolean): specifies if a user is allowed to change the password themselves when local auth is used (prop\_pwd\_change). If not set on users the global default server key cs.cws.pwd\_change is used as default. Admins can always change user passwords (including their own). - reroute\_gw (string): one of ‘disable’, ‘dns\_only’, ‘global’ Disables redirection of the default route and/or DNS on the client. This does not block it on the backend, if blocking on the backend is required, access lists should be added in addition. Defaults to ‘global’ if not set. The setting global will follow the configuration key ‘vpn.client.routing.reroute\_gw’.(prop\_reroute\_gw\_override) - allow\_generate\_profiles (prop\_autogenerate): allow users themselves to generate connection profiles |
| »»» name | string | false | none | the name of the user or group. |
| »»» deny | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»»» value | any | true | none | the value that this property has. If inherited is false, this is identical to inheritedValue |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | string | false | none | none |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | boolean | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» inherited | boolean | false | none | specifies if this value is inherited from an upper level if this |
| »»»» inherited\_source\_type | string | false | none | describes where the inherited values comes. This can be from the default user properties (**default**) or from a global configuration settings or from a group If the property is explicitly set (ie inherited is false), this property indicates what the property would inherit from if inherit is false. |
| »»»» inherited\_source\_name | string | false | none | for the inherited types where knowing the name of the source can be beneficial. Like the group name or in some cases the configuration key. If the property is explicitly set (ie inherited is false), this property indicates what the property would inherit from if inherit is false. |
| »»» deny\_web | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» admin | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» autologin | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» auth\_method | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» cc\_commands | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» totp | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» password\_strength | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» allow\_password\_change | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» reroute\_gw | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» allow\_generate\_profiles | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| »»» bypass\_subnets | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet)\] | false | none | Subnets or hosts (represented subnet with a /32 or /128 netmask) that are installed as bypass routes on the client, i.e. that will bypass the VPN and use the normal non-VPN connection. |
| »»»» ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| »»»» netip | string | false | none | the network IP address. |
| »»»» prefix\_length | integer | false | none | length of the prefix in CIDR notation |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userLevelOnlyProps](https://openvpn.net/as-docs/rest-api/#userlevelonlyprops) | false | none | Describes userprop properties that are exclusive to individual users and cannot be inherited from group or global levels. |
| »»» password\_defined | boolean | false | none | This indicates whether the user has a password set. The API will NOT provide the hash of the password but only the information if a user password has been set. |
| »»» mfa\_status | string | false | none | the status of the multi factor authentication. This is a read-only property that combines totp and totp\_locked into a single status. |
| »»» totp\_locked | boolean | false | none | specifies if the TOTP for the user is locked/enrolled. If true, secret is no longer viewable |
| »»» group | string | false | none | the group a user belongs too (conn\_group) |
| »»» static\_ipv4 | string | false | none | optional property. Maps to conn\_ip |
| »»» static\_ipv6 | string | false | none | optional property. Maps to conn\_ip6 |
| »»» dmz\_ip | \[[DMZIP](https://openvpn.net/as-docs/rest-api/#dmzip)\] | false | none | The IP addresses and port-ranges that are exposed on this client. |
| »»»» ip | string | true | none | the external IP address of the Access Server |
| »»»» protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol) | false | none | Specifies a Layer 4 protocol such as udp or tcp. |
| »»»» start\_port | integer | false | none | the starting port for the dmz. If not specified all ports will be forwarded |
| »»»» end\_port | integer | false | none | the end port of the ports that are being forwarded. If not specified only a single port (the start\_port) is forwarded. |
| »»» dmz\_ipv6 | \[[DMZIP](https://openvpn.net/as-docs/rest-api/#dmzip)\] | false | none | The IPv6 addresses and port-ranges that are exposed on this client. |
| »»» compile | boolean | false | none | If true the type is ‘user\_compile’ instead of ‘user\_connect’. |
| »»» totp\_secret | string | false | none | the TOTP secret code according to RFC 6238. Note, that this is value might not be present for locked users in later versions (pvt\_google\_auth\_secret). |
| »»» totp\_admin\_only | boolean | false | none | totp\_admin\_only only AS admins can generate and view Google Authenticator secrets (prop\_google\_auth\_admin\_locked) |
| »»» client\_to\_server\_subnets | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet)\] | false | none | \< Subnets that are behind the client. I.e. the client will be a router/gateway for the subnets specified in this array. On the server side, this is split into ipv4 and ipv6 subnets (c2s\_subnets and c2s\_subnets6) but this API represents that as a single list. Use the ipv6 flag of the subnet to determine the address family. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userPropScripts](https://openvpn.net/as-docs/rest-api/#userpropscripts) | false | none | This hold the attributes of the userprop that control client side scripting. It is not handled in a special way like passwords or group members. OpenAPI does not allow to specify description along with $ref so the description for the individual keys is in this descriptions. - Client side scripting: prop\_cli.script.\.\.\
- Client script env: prop\_cli.script\_env.win\|prop\_cli.script\_env.mac”
example environment variable: “prop\_cli.script\_env.win.MSI\_URL”: “https://secure.openvpn.net/tmp/bogi.msi”,
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| cli\_script\_connect\_win\_user\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_win\_user\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_win\_admin\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_win\_admin\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_mac\_user\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_mac\_user\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_mac\_admin\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_mac\_admin\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_win\_env | object | false | none | environment variables for the Windows script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
| cli\_script\_connect\_mac\_env | object | false | none | environment variables for the macOS script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue) | false | none | This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source. |
```json
{
"cli_script_connect_win_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"property2": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
}
}
}
```
#### userPropScriptsSet
The same as userPropScripts schema. With the diffirence that it is used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| cli\_script\_connect\_win\_user\_connect | string | false | none | none |
| cli\_script\_connect\_win\_user\_disconnect | string | false | none | none |
| cli\_script\_connect\_win\_admin\_connect | string | false | none | none |
| cli\_script\_connect\_win\_admin\_disconnect | string | false | none | none |
| cli\_script\_connect\_mac\_user\_connect | string | false | none | none |
| cli\_script\_connect\_mac\_user\_disconnect | string | false | none | none |
| cli\_script\_connect\_mac\_admin\_connect | string | false | none | none |
| cli\_script\_connect\_mac\_admin\_disconnect | string | false | none | none |
| cli\_script\_connect\_win\_env | object | false | none | environment variables for the Windows script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | string | false | none | none |
| cli\_script\_connect\_mac\_env | object | false | none | environment variables for the macOS script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | string | false | none | none |
```json
{
"cli_script_connect_win_user_connect": "string",
"cli_script_connect_win_user_disconnect": "string",
"cli_script_connect_win_admin_connect": "string",
"cli_script_connect_win_admin_disconnect": "string",
"cli_script_connect_mac_user_connect": "string",
"cli_script_connect_mac_user_disconnect": "string",
"cli_script_connect_mac_admin_connect": "string",
"cli_script_connect_mac_admin_disconnect": "string",
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": "string",
"property2": "string"
}
}
```
#### serviceStatusEnum
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | on |
| **anonymous** | disabled |
| **anonymous** | error |
| **anonymous** | enabled |
```json
"on"
```
#### serviceWarning
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| tag | string | false | none | A tag assigned to the type of warning/error message |
| message | string | false | none | A short summary of the warning in question |
| description | any | false | none | A longer more detailed description of the warning |
| severity | string | false | none | The level of the warning. The level error signals a hard error that prevents Access Server from starting and ok signal |
###### Enumerated Values
| Property | Value |
| --- | --- |
| severity | ok |
| severity | info |
| severity | warning |
| severity | critical |
| severity | error |
```json
{
"tag": "DCO_NOT_ACTIVE",
"message": "Insecure VPN cipher in use",
"description": "Insecure cipher DES-EDE3-CBC allowed for VPN encryption. Consider removing this cipher from vpn.server.data_ciphers (AES-256-GCM:DES-EDE3-CBC) and/or disabling vpn.server.enable_cipher_fallback (False)",
"severity": "ok"
}
```
#### serviceStatus
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| status | [serviceStatusEnum](https://openvpn.net/as-docs/rest-api/#servicestatusenum) | false | none | none |
| error | \[[serviceWarning](https://openvpn.net/as-docs/rest-api/#servicewarning)\] | false | none | a list of important error message/warnings that impact current operation |
```json
{
"status": "on",
"error": [
{
"tag": "DCO_NOT_ACTIVE",
"message": "Insecure VPN cipher in use",
"description": "Insecure cipher DES-EDE3-CBC allowed for VPN encryption. Consider removing this cipher from vpn.server.data_ciphers (AES-256-GCM:DES-EDE3-CBC) and/or disabling vpn.server.enable_cipher_fallback (False)",
"severity": "ok"
}
]
}
```
#### serverStatus
Provides the current status of the internal services running on the server.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| last\_restarted | string(date-time) | false | none | the last time the server was restarted |
| service\_status | object | false | none | an object containing the status of the various internal services. The key name holds the name of the service. |
| » **additionalProperties** | [serviceStatus](https://openvpn.net/as-docs/rest-api/#servicestatus) | false | none | none |
| auth\_module\_status | object | false | none | an object containing the status of the various authentication services. The key name holds the name of the service. |
| » **additionalProperties** | [serviceStatusEnum](https://openvpn.net/as-docs/rest-api/#servicestatusenum) | false | none | none |
```json
{
"last_restarted": "2019-08-24T14:15:22Z",
"service_status": {
"property1": {
"status": "on",
"error": []
},
"property2": {
"status": "on",
"error": []
}
},
"auth_module_status": {
"property1": "on",
"property2": "on"
}
}
```
#### serverInterface
Describes a Linux network interface along with its associated primary networks.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| name | any | false | none | the name identifying the interface |
| networks | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet)\] | false | none | IP addresses assigned to the interface |
```json
{
"name": "eth0",
"networks": [
{
"netip": "fd00::18cc:1b01:a772:50e1",
"ipv6": true,
"prefix_len": "64"
},
{
"netip": "10.0.0.1",
"ipv6": false,
"prefix_len": 25
},
{
"netip": "192.168.0.1",
"ipv6": false,
"prefix_len": 24
}
]
}
```
#### serverConfig
Describes global configuration settings for Access Server that are accessible to any authenticated user.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| control\_channel\_security | [controlChannelSecurity](https://openvpn.net/as-docs/rest-api/#controlchannelsecurity) | true | none | none |
| installers | \[[installerType](https://openvpn.net/as-docs/rest-api/#installertype)\] | true | none | \[Specifies the type of the installer binary to be generated.\] |
| hide\_profiles\_page | boolean | false | none | If True, the Connections profile page is hidden |
| password\_min\_len | integer | true | none | Minimal length for the password if strength check is enabled. |
| disable\_open\_in\_app | boolean | true | none | If True then disable in app on UI |
| admin\_port | integer | true | none | port for Admin site |
| shared\_origin | boolean | true | none | CWS and Admin ui are both available on same origin (protocol + hostname + port) as this API endpoint being called. |
| cws\_url | string | false | none | the url that is considered to host the client web services |
| admin\_url | string | false | none | the url that is considered to host the admin services |
```json
{
"control_channel_security": "none",
"installers": [
"win_v3"
],
"hide_profiles_page": true,
"password_min_len": 0,
"disable_open_in_app": true,
"admin_port": 0,
"shared_origin": true,
"cws_url": "https://as.example.com/",
"admin_url": "https://as.example.com/admin"
}
```
#### controlChannelSecurity
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | none |
| **anonymous** | tls-auth |
| **anonymous** | tls-crypt |
| **anonymous** | tls-crypt-v2 |
```json
"none"
```
#### serverInfo
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| version | string | false | none | the version number of Access Server |
| build | string | false | none | the build of Access Server. |
| web\_version | string | false | none | the build version number of Access Server UI |
| web\_override | boolean | false | none | if true the version of the web ui that is used comes from an override-web.zip instead of the bundled version |
| client\_version | string,null | false | none | version of the embedded client package. `null` if the user manually deleted the files of the openvpn-as-bundled-clients package |
| os\_distribution | string | false | none | a human readable identifier of the current (Linux) distribution like PRETTY\_NAME from /etc/os-release |
| architecture | string | false | none | the CPU architecture |
| cores | integer | false | none | the number of cores available to OpenVPN Access server. Typically identical to system\_cores. |
| system\_cores | any | false | none | the number of cores visible to the operating system |
| os\_hostname | string | false | none | Operating system’s hostname |
###### Enumerated Values
| Property | Value |
| --- | --- |
| architecture | arm64 |
| architecture | amd64 |
```json
{
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": "27",
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"system_cores": null,
"os_hostname": "access-server-os-hostname"
}
```
#### eulaStatus
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| eula\_version\_as | integer | false | none | The version of the AS EULA |
| eula\_web\_hash | string(sha256) | false | none | A SHA256 string in hex format without : separators |
| eula\_accepted | boolean | false | none | indicates whether the config setting (aui.eula\_version) has the same value as eula\_version\_as |
```json
{
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
```
#### notificationMessage
notification msg stored in notificationdb
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| notification\_type | string | true | none | the type of notification |
###### Enumerated Values
| Property | Value |
| --- | --- |
| notification\_type | CLUSTER\_RESTART\_PENDING |
| notification\_type | NODE\_RESTARTED |
```json
{
"notification_type": "CLUSTER_RESTART_PENDING"
}
```
#### clusterProps
Properties shared across all nodes in an Access Server cluster.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| rr\_dns\_hostname | string | false | none | the Round-Robin hostname that uniquely identifies the cluster |
| rr\_dns\_new\_nodes | boolean | false | none | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
```json
{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
```
#### clusterNode
Describes a node in the cluster. The certificate field represents the certificate the node presents on its api\_endpoint and is used to verify the node's identity.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| name | string | true | none | the name that uniquely identifies the cluster node \[node\_name\] |
| api\_endpoint | [apiEndpoint](https://openvpn.net/as-docs/rest-api/#apiendpoint) | false | none | The API endpoint used to communicate with a specific node. Must be in the format https://ip-or-hostname:port. The https scheme is required because the certificateFingerprint is used by the HTTPS client to verify the identity of the node. |
| certificate\_fingerprint | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint) | false | none | The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C"
}
```
#### clusterNodeJoinRequest
Describes a node requesting to join the cluster. The certificate field represents the certificate the node presents on its `api_endpoint` and is used to verify the node’s identity.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterNode](https://openvpn.net/as-docs/rest-api/#clusternode) | false | none | Describes a node in the cluster. The certificate field represents the certificate the node presents on its api\_endpoint and is used to verify the node's identity. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » mysql\_uri\_parts | [mysqlUriParts](https://openvpn.net/as-docs/rest-api/#mysqluriparts) | false | none | a structure describing parts of a MySQL URI. The database name and the query are neither supported nor expected by the admin UI’s cluster setup pages’ logic, so these fields are not included. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}
}
```
#### clusterNodeCreateRequest
Defines the properties common to all nodes in the cluster.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterNodeJoinRequest](https://openvpn.net/as-docs/rest-api/#clusternodejoinrequest) | false | none | Describes a node requesting to join the cluster. The certificate field represents the certificate the node presents on its `api_endpoint` and is used to verify the node’s identity. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops) | false | none | Properties shared across all nodes in an Access Server cluster. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » rr\_update\_node | boolean | false | none | if true: update host.name in confdb\_local to rr\_dns\_hostname in clusterdb when creating the cluster. if false: do not use rr\_dns\_hostname to update host.name in confdb\_local, at cluster creation time. This is to provide admin the flexibility to update host.name to rr\_dns\_hostname at a later stage than cluster creation. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysql_uri_parts": {
"host": "string",
"port": 1,
"username": "string",
"password": "string"
},
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}
```
#### mysqlUriParts
a structure describing parts of a MySQL URI. The database name and the query are neither supported nor expected by the admin UI’s cluster setup pages’ logic, so these fields are not included.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| host | string | true | none | none |
| port | integer | true | none | none |
| username | string | true | none | none |
| password | string | true | none | none |
```json
{
"host": "string",
"port": 1,
"username": "string",
"password": "string"
}
```
#### profileRequest
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| username | [username](https://openvpn.net/as-docs/rest-api/#username) | false | none | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | true | none | Specifies the connection profile type. |
| tls\_crypt\_v2 | boolean | false | none | The client is capable of TLS-Crypt v2 |
| comment | string | false | none | A user-defined comment |
| ignore\_missing\_user | any | false | none | if this is flag, which requires admin rights, is set, a profile will be created even if the specified user does not exist. |
```json
{
"username": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}
```
#### installerProfileRequest
Fields used to request a download URL for a specific installer profile.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| user | [username](https://openvpn.net/as-docs/rest-api/#username) | false | none | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| installer\_type | [installerType](https://openvpn.net/as-docs/rest-api/#installertype) | true | none | Specifies the type of the installer binary to be generated. |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | false | none | Specifies the connection profile type. |
| tls\_crypt\_v2 | boolean | false | none | The client is capable of TLS-Crypt v2 |
```json
{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}
```
#### commonPaginationParameters
Shared parameters used by endpoints that support pagination. The `order_by` and `sort_by` fields depend on the type of object being paginated.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| page\_size | integer | false | none | number of the profiles that are returned |
| offset | integer | false | none | offset for pagination |
| sort\_by | [sortingDirection](https://openvpn.net/as-docs/rest-api/#sortingdirection) | false | none | The direction in which to sort results (e.g., ascending or descending). |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc"
}
```
#### profileRequestParameters
Defines filters and parameters for requesting user profiles.
Notes: Some search fields may not be indexed in the backend database, which can impact performance. Non-admin users can only filter by their own username; using another username will result in an error.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters) | false | none | Shared parameters used by endpoints that support pagination. The `order_by` and `sort_by` fields depend on the type of object being paginated. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [certProfileSorting](https://openvpn.net/as-docs/rest-api/#certprofilesorting) | false | none | Defines the attribute used to sort certificate profiles. |
| » filters | object | false | none | none |
| »» username | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» serial | [filterInteger](https://openvpn.net/as-docs/rest-api/#filterinteger) | false | none | Specifies a filter for integer-based attributes using a defined operation. |
| »» autologin | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| »» tls\_crypt\_v2 | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| »» last\_used | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» not\_before | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» not\_after | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» comment | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» signing\_ca\_cn | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere) | false | none | Applies a substring match across multiple fields. Returns results if the specified value matches any part of any listed field. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"username": {
"operation": "substring",
"value": "vio"
},
"serial": {
"value": 400,
"operation": "less_than"
},
"autologin": {
"value": true
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
#### userRequestParameters
Specifies filters for requesting user parameters.
When multiple filters are used, only items matching all filters are returned. The ‘anywhere’ filter is a special case and must be used alone.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters) | false | none | Shared parameters used by endpoints that support pagination. The `order_by` and `sort_by` fields depend on the type of object being paginated. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [userSorting](https://openvpn.net/as-docs/rest-api/#usersorting) | false | none | Defines the attribute used to sort user profiles. |
| » filters | any | false | none | none |
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »»» group | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [commonUserGroupFilters](https://openvpn.net/as-docs/rest-api/#commonusergroupfilters) | false | none | Filters that apply to both user and group requests. |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » users | \[[username](https://openvpn.net/as-docs/rest-api/#username)\] | false | none | a list of usernames that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that usernames that are not found in the backend will be missing from the response. |
| » proplist | [userPropList](https://openvpn.net/as-docs/rest-api/#userproplist) | false | none | A list of user properties to retrieve. If set to null, all properties for the user or group are returned. Otherwise, only the specified properties in the list will be included in the response. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "admin",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"group": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"users": [
"niccolo@paganini.it"
],
"proplist": [
"string"
]
}
```
#### commonUserGroupFilters
Filters that apply to both user and group requests.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| admin | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| autologin | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere) | false | none | Applies a substring match across multiple fields. Returns results if the specified value matches any part of any listed field. |
```json
{
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": [
"username",
"group"
]
}
}
```
#### tokenRequestParameters
Parameters used to create a new token URL. Non-admin users should typically only specify the profile type. Setting other parameters above their default values may result in errors.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| lifetime | integer | false | none | Optional lifetime in seconds that the token should be valid for. Longer lifetimes than default require admin privileges. |
| usages | integer | false | none | Optional number of usages that this token can be used to generate a profile. Defaults to a single use if not provided. Specifying more than one usage requires admin privileges. |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype) | true | none | Specifies the connection profile type. |
| username | [username](https://openvpn.net/as-docs/rest-api/#username) | false | none | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| comment | string | false | none | Optional comment for the profile that will be stored with the token and applied when the profile is generated. |
```json
{
"lifetime": 1,
"usages": 1,
"profile_type": "autologin",
"username": "niccolo@paganini.it",
"comment": "connected from my iPhone"
}
```
#### logDBRequestParameters
Filters and parameters for querying the log database. Only selected fields from ‘logDBRecord’ are supported, and some searches may be slow due to the lack of database indexing.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters) | false | none | Shared parameters used by endpoints that support pagination. The `order_by` and `sort_by` fields depend on the type of object being paginated. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [logDBSortingFields](https://openvpn.net/as-docs/rest-api/#logdbsortingfields) | false | none | Enum of valid sorting fields for querying the log database. |
| » filters | object | false | none | none |
| »» start\_time | [filterTimeOrDuration](https://openvpn.net/as-docs/rest-api/#filtertimeorduration) | false | none | Specifies a time range to filter results by a given attribute. You can define the range using either absolute timestamps or relative time values. If only one endpoint (start or end) is provided, the range is considered open-ended. For example, a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). The same logic applies relative time inputs. |
| »» timestamp | [filterTimeOrDuration](https://openvpn.net/as-docs/rest-api/#filtertimeorduration) | false | none | Specifies a time range to filter results by a given attribute. You can define the range using either absolute timestamps or relative time values. If only one endpoint (start or end) is provided, the range is considered open-ended. For example, a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). The same logic applies relative time inputs. |
| »» duration | [filterDuration](https://openvpn.net/as-docs/rest-api/#filterduration) | false | none | Specifies a filter for duration-based attributes using a defined operation. |
| »» node | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» username | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» active | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| »» error | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool) | false | none | Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid. |
| »» service | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» virtual\_ipv4\_address | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» bytes\_sent | [filterBandwidth](https://openvpn.net/as-docs/rest-api/#filterbandwidth) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» bytes\_received | [filterBandwidth](https://openvpn.net/as-docs/rest-api/#filterbandwidth) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» gui\_version | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» version | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» platform | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» protocol | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| »» anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere) | false | none | Applies a substring match across multiple fields. Returns results if the specified value matches any part of any listed field. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "node",
"filters": {
"start_time": {
"start_relative": "20d",
"end_relative": "15d 20m"
},
"timestamp": {
"start_relative": "20d",
"end_relative": "15d 20m"
},
"duration": {
"value": "20d",
"operation": "less_than"
},
"node": {
"operation": "substring",
"value": "vio"
},
"username": {
"operation": "substring",
"value": "vio"
},
"active": {
"value": true
},
"error": {
"value": true
},
"service": {
"operation": "substring",
"value": "vio"
},
"virtual_ipv4_address": {
"operation": "substring",
"value": "vio"
},
"bytes_sent": {
"value": "20kb",
"operation": "less_than"
},
"bytes_received": {
"value": "20kb",
"operation": "less_than"
},
"gui_version": {
"operation": "substring",
"value": "vio"
},
"version": {
"operation": "substring",
"value": "vio"
},
"platform": {
"operation": "substring",
"value": "vio"
},
"protocol": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
#### filterTimeOrDuration
Specifies a time range to filter results by a given attribute.
You can define the range using either absolute timestamps or relative time values. If only one endpoint (start or end) is provided, the range is considered open-ended. For example, a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). The same logic applies relative time inputs.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| start | string(date-time) | false | none | none |
| end | string(date-time) | false | none | none |
| start\_relative | string | false | none | none |
| end\_relative | string | false | none | none |
```json
{
"start_relative": "20d",
"end_relative": "15d 20m"
}
```
#### filterBandwidth
This specifies that the result should be filtered by this attribute with the specified operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | any | true | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | string | false | none | none |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | integer | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | less\_than |
| operation | greater\_than |
```json
{
"value": "20kb",
"operation": "less_than"
}
```
#### filterString
Specifies a filter for string-based attributes using a defined operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | substring |
| operation | not\_equal |
```json
{
"operation": "substring",
"value": "vio"
}
```
#### filterDuration
Specifies a filter for duration-based attributes using a defined operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | less\_than |
| operation | greater\_than |
```json
{
"value": "20d",
"operation": "less_than"
}
```
#### filterInteger
Specifies a filter for integer-based attributes using a defined operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | integer | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | less\_than |
| operation | greater\_than |
| operation | not\_equal |
```json
{
"value": 400,
"operation": "less_than"
}
```
#### filterTime
This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞).
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| start | string(date) | false | none | none |
| end | string(date) | false | none | none |
```json
{
"start": "2019-08-24",
"end": "2019-08-24"
}
```
#### filterBool
Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | boolean | true | none | none |
```json
{
"value": true
}
```
#### filterAnywhere
Applies a substring match across multiple fields. Returns results if the specified value matches any part of any listed field.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | false | none | the substring to search in all specified fields |
| fields | \[string\] | false | none | names of the fields to be searched |
```json
{
"value": "bass",
"fields": [
"username",
"group"
]
}
```
#### accessControlRuleTypeEnum
Rules can have one of these types.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | Rules can have one of these types. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | domain\_routing |
| **anonymous** | filter |
```json
"domain_routing"
```
#### accessControlRuleMatchTypeEnum
Rules can have one of these match types.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | Rules can have one of these match types. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | domain |
| **anonymous** | not\_domain |
| **anonymous** | subdomain |
| **anonymous** | not\_subdomain |
| **anonymous** | domain\_or\_subdomain |
| **anonymous** | not\_domain\_or\_subdomain |
```json
"domain"
```
#### accessControlRuleActionEnum
Rules can have one of these actions.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | Rules can have one of these actions. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | route |
| **anonymous** | nat |
| **anonymous** | deny |
| **anonymous** | bypass |
```json
"route"
```
#### filterAccessRuleType
Specifies a filter for access control rule types.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | [accessControlRuleTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruletypeenum) | true | none | Rules can have one of these types. |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | not\_equal |
```json
{
"value": "domain_routing",
"operation": "equal"
}
```
#### filterAccessRuleMatchType
Specifies a filter for access control rule match types.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | [accessControlRuleMatchTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolrulematchtypeenum) | true | none | Rules can have one of these match types. |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | not\_equal |
```json
{
"value": "domain",
"operation": "equal"
}
```
#### groupRequestParameters
Specifies filters and pagination parameters for group-related API requests. The order\_by and sort\_by fields depend on the properties available in the group objects being queried.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters) | false | none | Shared parameters used by endpoints that support pagination. The `order_by` and `sort_by` fields depend on the type of object being paginated. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [groupSorting](https://openvpn.net/as-docs/rest-api/#groupsorting) | false | none | Defines the attribute used to sort groups. |
| » filters | any | false | none | none |
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [commonUserGroupFilters](https://openvpn.net/as-docs/rest-api/#commonusergroupfilters) | false | none | Filters that apply to both user and group requests. |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » enumerate\_members | [enumerateMembersParameter](https://openvpn.net/as-docs/rest-api/#enumeratemembersparameter) | false | none | If set to true, the response includes a list of all group members; otherwise, only the member count is returned. |
| » groups | \[[groupname](https://openvpn.net/as-docs/rest-api/#groupname)\] | false | none | a list of groups that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that groups that are not found in the backend will be missing from the response. |
| » proplist | [userPropList](https://openvpn.net/as-docs/rest-api/#userproplist) | false | none | A list of user properties to retrieve. If set to null, all properties for the user or group are returned. Otherwise, only the specified properties in the list will be included in the response. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "name",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"enumerate_members": true,
"groups": [
"string"
],
"proplist": [
"string"
]
}
```
#### accessListRequestParameters
Parameters used when querying access lists.
The `name` field refers to either a user or group name.
Due to the way access control list (ACL) entries are stored as strings in the database, sorting and filtering options are limited.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| order\_by | string | false | none | none |
| filters | object | false | none | filters for the access list objects. |
| » internal\_representation | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| » groupname | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| » username | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring) | false | none | Specifies a filter for string-based attributes using a defined operation. |
| » object\_type | string | false | none | Only return users or groups in the response. |
| groups | \[[groupname](https://openvpn.net/as-docs/rest-api/#groupname)\] | false | none | a list of groups that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that groups that are not found in the backend will be missing from the response. |
| users | \[[username](https://openvpn.net/as-docs/rest-api/#username)\] | false | none | a list of usernames that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that usernames that are not found in the backend will be missing from the response. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| order\_by | internal\_prop\_representation |
| order\_by | name |
| object\_type | user |
| object\_type | group |
| object\_type | all |
```json
{
"order_by": "internal_prop_representation",
"filters": {
"internal_representation": {
"operation": "substring",
"value": "vio"
},
"groupname": {
"operation": "substring",
"value": "vio"
},
"username": {
"operation": "substring",
"value": "vio"
},
"object_type": "user"
},
"groups": [
"string"
],
"users": [
"niccolo@paganini.it"
]
}
```
#### enumerateMembersParameter
If set to true, the response includes a list of all group members; otherwise, only the member count is returned.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | boolean | false | none | If set to true, the response includes a list of all group members; otherwise, only the member count is returned. |
```json
true
```
#### userPropList
A list of user properties to retrieve. If set to null, all properties for the user or group are returned. Otherwise, only the specified properties in the list will be included in the response.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | array,null | false | none | A list of user properties to retrieve. If set to null, all properties for the user or group are returned. Otherwise, only the specified properties in the list will be included in the response. |
```json
[
"string"
]
```
#### DMZIP
A DMZ IP and port that will be forwarded to the client. This corresponds to the internal dmz\_ip user property, formatted as `IP[:proto/start_port[-end_port]]`.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ip | string | true | none | the external IP address of the Access Server |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol) | false | none | Specifies a Layer 4 protocol such as udp or tcp. |
| start\_port | integer | false | none | the starting port for the dmz. If not specified all ports will be forwarded |
| end\_port | integer | false | none | the end port of the ports that are being forwarded. If not specified only a single port (the start\_port) is forwarded. |
```json
{
"ip": "123.7.3.1",
"start_port": 7000,
"end_port": 7111,
"protocol": "udp"
}
```
#### IpService
Describes a network service using an IP protocol — either TCP, UDP, or ICMP.
##### Properties
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [portRange](https://openvpn.net/as-docs/rest-api/#portrange) | false | none | Describes a layer 4 TCP or UDP port or port-range. The protocol must be either udp or tcp. |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [icmpService](https://openvpn.net/as-docs/rest-api/#icmpservice) | false | none | Describes an ICMP service type. The protocol property value is always ICMP. |
```json
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
```
#### icmpService
Describes an ICMP service type. The protocol property value is always ICMP.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol) | false | none | Specifies a Layer 4 protocol such as udp or tcp. |
| type | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | icmp-any |
| type | icmp-echo-reply |
| type | icmp-destination-unreachable |
| type | icmp-network-unreachable |
| type | icmp-host-unreachable |
| type | icmp-protocol-unreachable |
| type | icmp-port-unreachable |
| type | icmp-fragmentation-needed |
| type | icmp-source-route-failed |
| type | icmp-network-unknown |
| type | icmp-host-unknown |
| type | icmp-network-prohibited |
| type | icmp-host-prohibited |
| type | icmp-TOS-network-unreachable |
| type | icmp-TOS-host-unreachable |
| type | icmp-communication-prohibited |
| type | icmp-host-precedence-violation |
| type | icmp-precedence-cutoff |
| type | icmp-source-quench |
| type | icmp-redirect |
| type | icmp-network-redirect |
| type | icmp-host-redirect |
| type | icmp-TOS-network-redirect |
| type | icmp-TOS-host-redirect |
| type | icmp-echo-request |
| type | icmp-router-advertisement |
| type | icmp-router-solicitation |
| type | icmp-time-exceeded |
| type | icmp-ttl-zero-during-transit |
| type | icmp-ttl-zero-during-reassembly |
| type | icmp-parameter-problem |
| type | icmp-ip-header-bad |
| type | icmp-required-option-missing |
| type | icmp-timestamp-request |
| type | icmp-timestamp-reply |
| type | icmp-address-mask-request |
```json
{
"protocol": "tcp",
"type": "icmp-any"
}
```
#### portRange
Describes a layer 4 TCP or UDP port or port-range. The protocol must be either udp or tcp.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol) | true | none | Specifies a Layer 4 protocol such as udp or tcp. |
| start\_port | integer | true | none | The start port of the port range |
| end\_port | integer | false | none | The end port of the port range. If not specified, the range will consist of only one single port (start\_port) |
```json
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
```
#### layer4protocol
Specifies a Layer 4 protocol such as udp or tcp.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | Specifies a Layer 4 protocol such as udp or tcp. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | tcp |
| **anonymous** | udp |
| **anonymous** | icmp |
```json
"tcp"
```
#### accessRouteListItem
Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works.
- The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property.
- The user/group require the username/groupname property
- the nat and route type require the subnet property.
Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class.
Either username or groupname is set to indicate whether this is a user or group assigned access rules.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| username | [username](https://openvpn.net/as-docs/rest-api/#username) | false | none | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| groupname | [groupname](https://openvpn.net/as-docs/rest-api/#groupname) | false | none | Name of a user group used in user management. specify a group name. |
| access\_route | any | false | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | [accessRoute](https://openvpn.net/as-docs/rest-api/#accessroute) | false | none | Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works. - The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property. - The user/group require the username/groupname property - the nat and route type require the subnet property. Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class. |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | null | false | none | indicator that routes of this type should be deleted |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| type | string | false | none | the type of access list this item this is in the user/group. |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
not
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
not
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | access\_from\_ipv6 |
| type | access\_from\_ipv4 |
| type | access\_to\_ipv4 |
| type | access\_to\_ipv6 |
```json
{
"username": "johann",
"access_route": {
"type": "route",
"accept": "true",
"subnet": {
"ipv6": true,
"prefix_length": 64,
"netip": "2001:bach:ce1:10::0"
}
},
"type": "access_to_ipv4"
}
```
#### accessRoute
Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works. - The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property.
- The user/group require the username/groupname property
- the nat and route type require the subnet property.
Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| type | string | false | none | none |
| accept | boolean | false | none | specifies if we accept or deny this particular access |
| username | [username](https://openvpn.net/as-docs/rest-api/#username) | false | none | A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations. |
| groupname | [groupname](https://openvpn.net/as-docs/rest-api/#groupname) | false | none | Name of a user group used in user management. specify a group name. |
| subnet | [accessRouteSubnet](https://openvpn.net/as-docs/rest-api/#accessroutesubnet) | false | none | The definition of the subnet used by the nat and route accessRoute classes. Each one is a subnet with one or more port ranges For reference, the internal representation on the Access Server properties looks like this: - 192.168.4.0/24 - 10.10.0.0/24:https,udp/1194,tcp/1194 - 192.168.99.0/24::R - 192.168.99.0/24:https,udp/1194,tcp/1194,udp/2000-2999:R - 2001:608:3:814::0/64 |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | user |
| type | group |
| type | route |
| type | nat |
| type | all |
| type | all\_vpn\_clients |
| type | all\_s2c\_subnets |
```json
{
"type": "user",
"accept": true,
"username": "niccolo@paganini.it",
"groupname": "string",
"subnet": {
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false,
"service": [
{}
]
}
}
```
#### accessRouteSubnet
The definition of the subnet used by the nat and route accessRoute classes. Each one is a subnet with one or more port ranges
For reference, the internal representation on the Access Server properties looks like this: - 192.168.4.0/24 - 10.10.0.0/24:https,udp/1194,tcp/1194 - 192.168.99.0/24::R - 192.168.99.0/24:https,udp/1194,tcp/1194,udp/2000-2999:R - 2001:608:3:814::0/64\|https,udp/1194,tcp/1194,udp/2000-2999\|R - 10.0.0.7/24:icmp-any,rdp,imaps - 10.0.0.1/25:icmp-TOS-host-redirect
Note that the services array is optional. A missing service array indicates that the whole subnet is affected regardless of the used layer 4 service (icmp, tcp, udp or other IP protocol)
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet) | false | none | Describes an IP subnet. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » service | \[[IpService](https://openvpn.net/as-docs/rest-api/#ipservice)\] | false | none | \[Describes a network service using an IP protocol — either TCP, UDP, or ICMP.\] |
```json
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false,
"service": [
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
]
}
```
#### accessControlResponseRuleset
Represents an access control ruleset.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| owner | string | false | none | Name of the assignee of this ruleset. |
| owner\_type | string | false | none | Type of the assignee of this ruleset. |
| id | integer | false | none | The ruleset ID. |
| name | string | false | none | Name of the ruleset. |
| position | integer | false | none | Rulesets are sorted in ascending order by this value. |
| comment | string | false | none | Comment for this ruleset. |
```json
{
"owner": "string",
"owner_type": "string",
"id": 0,
"name": "string",
"position": 0,
"comment": "string"
}
```
#### newAccessControlRule
Represents a new access control rule.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ruleset\_id | integer | true | none | The ID of the ruleset this rule is assigned to. |
| type | [accessControlRuleTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruletypeenum) | true | none | The type of the rule. |
| match\_type | [accessControlRuleTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruletypeenum) | true | none | The match type of the rule. |
| match\_data | string | true | none | The match data. |
| action | [accessControlRuleActionEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruleactionenum) | true | none | The action to perform, when this rule matches. |
| position | integer | true | none | The position of this rule within the other rules in the ruleset. |
| comment | string | true | none | Free text comment assigned to this rule. |
```json
{
"ruleset_id": 1,
"type": "domain_routing",
"match_type": "domain_or_subdomain",
"match_data": "doggo.com",
"action": "deny",
"position": 5000,
"comment": "my cat's favorite rule"
}
```
#### existingAccessControlRule
Represents an existing access control rule.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| id | integer | true | none | The rule ID. |
| ruleset\_id | integer | true | none | The ID of the ruleset this rule is assigned to. |
| type | [accessControlRuleTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruletypeenum) | true | none | The type of the rule. |
| match\_type | [accessControlRuleTypeEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruletypeenum) | true | none | The match type of the rule. |
| match\_data | string | true | none | The match data. |
| action | [accessControlRuleActionEnum](https://openvpn.net/as-docs/rest-api/#accesscontrolruleactionenum) | true | none | The action to perform, when this rule matches. |
| position | integer | true | none | The position of this rule within the other rules in the ruleset. |
| comment | string | true | none | Free text comment assigned to this rule. |
```json
{
"id": 1,
"ruleset_id": 1,
"type": "domain_routing",
"match_type": "domain_or_subdomain",
"match_data": "doggo.com",
"action": "deny",
"position": 5000,
"comment": "my cat's favorite rule"
}
```
#### userRulesetsAddMap
Ruleset mappings for a subject. The subject name is given as the key.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **additionalProperties** | \[object\] | false | none | List of rulesets to map to the subject |
| » ruleset\_id | integer | true | none | The ID of the ruleset to associate with the subject. |
| » position | integer | true | none | Position of the ruleset within all subject’s sets. Sorted ascending. |
```json
{
"property1": [
{
"ruleset_id": 0,
"position": 0
}
],
"property2": [
{
"ruleset_id": 0,
"position": 0
}
]
}
```
#### userRulesetsDeleteMap
Ruleset mappings to delete for a subject. The subject name is given as the key.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **additionalProperties** | object | false | none | none |
| » ruleset\_ids | \[integer\] | false | none | A list of ruleset IDs to delete for the subject.. |
```json
{
"property1": {
"ruleset_ids": [
0
]
},
"property2": {
"ruleset_ids": [
0
]
}
}
```
#### IPsubNet
Describes an IP subnet.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| netip | string | false | none | the network IP address. |
| prefix\_length | integer | false | none | length of the prefix in CIDR notation |
```json
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false
}
```
#### groupIpRange
An IP range that defines the allowed IP addresses for a group. Represented on the backend as one of the following formats:
- “first\_ip-last\_ip”
- “first\_ip~numberOfIps”
- “first\_ip:last\_ip” (IPv4 only, deprecated)
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 range |
| first\_ip | string | false | none | the start address of the IP range. |
| last\_ip | string | false | none | the end address of the IP range. |
```json
{
"ipv6": true,
"first_ip": "fd00::18cc:1b01:a772:50e1",
"last_ip": "fd00::18cc:1b01:a772:80e1"
}
```
#### failOverTestResult
The result of a single failover test.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| friendly | string | false | none | Human readable interpretation of the test |
| status | boolean | true | none | Whether this test succeeded or not |
| message | string | true | none | detailed string of the test result |
```json
{
"friendly": "string",
"status": true,
"message": "string"
}
```
#### failOverTestStatus
The result of running the failover tests. The failover test runs a number of subtests. Note that if the connectivity test fails, often the other tests will fail as well.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ucarp | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| license\_primary | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| license\_secondary | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| connectivity | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
```json
{
"ucarp": {
"friendly": "string",
"status": true,
"message": "string"
},
"license_primary": {
"friendly": "string",
"status": true,
"message": "string"
},
"license_secondary": {
"friendly": "string",
"status": true,
"message": "string"
},
"connectivity": {
"friendly": "string",
"status": true,
"message": "string"
}
}
```
#### AcmeTLSAlpnChallenge
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| servername | string | true | none | the servername (used in SNI) that this certificate should be presented for |
| certificate | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate) | true | none | A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`. |
| private\_key | [pemEncodedPrivateKey](https://openvpn.net/as-docs/rest-api/#pemencodedprivatekey) | true | none | A private key in PEM format. This representation typically begins with `-----BEGIN PRIVATE KEY-----`, contains base64-encoded data, and ends with `-----END PRIVATE KEY-----`. |
```json
{
"servername": "string",
"certificate": "string",
"private_key": "string"
}
```
#### AcmeChallenge
Provides a list of X509 certificates and server names that the webserver should use to answer ACME tls-alpn-01 challenges
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| expiry | integer | false | none | A timeout in seconds after which the web server should no longer serve the challenge certificates |
| tls\_alpn\_challenges | \[[AcmeTLSAlpnChallenge](https://openvpn.net/as-docs/rest-api/#acmetlsalpnchallenge)\] | true | none | A list of tls-alpn-01 challenge certificates |
```json
{
"expiry": 0,
"tls_alpn_challenges": [
{
"servername": "string",
"certificate": "string",
"private_key": "string"
}
]
}
```
## Web API v0.1
The Access Server Web API v0.1 is available in Access Server 3.0.0–3.1.0. For the newer v0.2 reference, which covers Access Server 3.2.0 and newer, see [Web API v0.2](https://openvpn.net/as-docs/rest-api/#web-api-v0-2).
### OpenVPN Access Server Web API v0.1
This API provides the functionality required to download connection profiles, manage clients, and operate the Admin Web UI programmatically.
#### Conventions
| **Element** | **Convention** |
| --- | --- |
| Field names | snake\_case |
| URLs | kebab-case |
| Other identifiers | camelCase |
> **Important**
>
> - This API isn't the latest edition. Upgrade Access Server for the latest API.
> - The API supports proxying requests to other nodes in an Access Server cluster. Proxying is only applicable to admin endpoints.
> - We have made every effort to keep this documentation accurate, but minor discrepancies with the implementation may exist.
#### Swagger UI
To browse this API interactively, navigate to `/api/docs` on your Access Server. Ensure you've enabled access by setting `openapi.web_access` to `1`:
```
sacli --key "openapi.web_access" --value 1 ConfigPut
```
Alternatively, set this in the Admin Web UI Config Editor.
#### Base URLs
- `/api`
- `https://your-access-server.example.com/api/`
### Authentication
- API Key (AuthToken)
- Parameter Name: **X-OpenVPN-As-AuthToken**, in: header. This is an opaque token that allows using the authenticated method. The token will expire after a certain amount of time unless it is renewed through the renewal API. While we might use a JWT for this, the API consumer should not assume anything about the format or content of this string. JWT with default encryption/authentication appears not to be FIPS compatible.
- API Key (ProfileDownloadToken)
- Parameter Name: **token**, in: query. This is a string-token that can be used to download OpenVPN Connection Profile or installer file. Typically, e.g. for installer download and OpenVPN connection profile download, this token is generated as a token, that can be used only once.
- HTTP Authentication, scheme: basic a basic auth with user and password. This methods uses a fairly non-standard challenge/resposne method if required that is documented under https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#challengeresponse-authentication
### auth
APIs directly related to authenticating to the API
#### authByUserAndPw
`POST /auth/login/userpassword`
provides a opaque token to authenticate any APIs that require authentication
##### Body parameter
```json
{
"username": "string",
"password": "string",
"totp": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [userAndPwLogin](https://openvpn.net/as-docs/rest-api/#userandpwlogin-1) | false | none |
| » username | body | string | true | The user name for login. Note that if this is case-sensitive or not depends on the OpenVPN Access Server configuration. |
| » password | body | string | true | The password for login in clear text |
| » totp | body | string | false | Optional TOTP token for the user when wishing to do all MFA credentials in one go |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful auth | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse-1) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | missing MFA or ask to login via SAML workflow | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | wrong user and/or password or user access denied | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 409 | [Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8) | MFA enrollment is required. The intermediate auth token will be returned. This auth token should be used for enrolllment. | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse-1) |
##### Response Schema
Status Code **401**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » MFAChallenge | [MFAChallenge](https://openvpn.net/as-docs/rest-api/#mfachallenge) | false | none | none |
| »» echo | boolean | true | none | If true, the entered code should be displayed in cleartext. Otherwise masked like a password. |
| »» challenge | string | true | none | The text presented to the user when asking for the challenge. |
| »» challenge\_context | string | true | none | Often authentication backends require the challenge to be answered in the same session as the initial user/password. This allows tying the MFA answer to the initial authentication attempt. |
This operation does not require authentication
```javascript
const inputBody = '{
"username": "string",
"password": "string",
"totp": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/userpassword',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authMFASession
`POST /auth/login/mfaauth`
Provides an API to continue the authentication after a user/password authentication attempt that yielded a MFA challenge.
##### Body parameter
```json
{
"response": "pa$$word",
"challenge_context": "FJAIIXMAIOFLGAK23",
"username": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [MFAResponse](https://openvpn.net/as-docs/rest-api/#mfaresponse-1) | true | none |
| » response | body | string(password) | false | the user’s response to the MFA challenge |
| » challenge\_context | body | string | false | The challenge context that was in the MFAChallenge. |
| » username | body | string | true | The user name for login |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful auth | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | wrong authentication info | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const inputBody = '{
"response": "pa$$word",
"challenge_context": "FJAIIXMAIOFLGAK23",
"username": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/mfaauth',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authBySAMLAssertion
`POST /auth/login/saml-assertion`
provides a opaque token to authenticate any APIs that require authentication
##### Body parameter
```json
{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [samlLogin](https://openvpn.net/as-docs/rest-api/#samllogin-1) | true | none |
| » assertion | body | string(xml) | true | SAML Assertion in xml format , encoded as base64-string |
| » relay\_state | body | string | false | Optional relay state identifying the type of SAML request. If not passed or empty, defaults to cws |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful auth | [loginResponse](https://openvpn.net/as-docs/rest-api/#loginresponse-1) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Wrong RelayState parameter or Invalid SAML assertion | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | Invalid authentication assertion request. Returned when status of authentication was not handled or unknown. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User access denied or Account configuration problem or no valid SAML configuration or This profile requires web based SAML Authentication. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const inputBody = '{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('/api/auth/login/saml-assertion',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### authRenewToken
`POST /auth/token/renew`
provides a new opaque token to that extends the lifetime of the previous token
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful auth | [authTokenResponse](https://openvpn.net/as-docs/rest-api/#authtokenresponse) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | the old token has expired and can no longer be renewed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Token renewal is no longer allowed. | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/token/renew',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
#### changePasswordLocalUser
`POST /auth/password/change`
Allows to change a local password. Note to verify that the user knows the old password, this needs to be used with an auth token that has been obtained very recently (or auth token issued to an admin user). This operation will only allow admin auth token or very recently issued user auth token to ensure that the user knows the old password. The consumer of this API will need to issue a new user token as part of flow to use the API. By very recent we mean very recent is a small time period like 30s.
##### Body parameter
```json
{
"username": "string",
"new_password": "pa$$word"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Password has changed successfully | Inline |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | Login failed | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Forbidden. Auth token was not recent enough or security criteria of new password not met. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » detail | string | false | none | none |
Status Code **401**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » detail | string | false | none | none |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"username": "string",
"new_password": "pa$$word"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/password/change',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"detail": "string"
}
```
#### enrollUserMFA
`POST /auth/mfa/enroll`
enrolls a user into MFA by providing a valid MFA token. After the enrollment auth token that has been generated on the first MFA stage can be used as a regular one. This also provides a fully authenticated auth-token as response that can be used without having to login again and going through the MFA process if no target user was provided to the API. Otherwise only the username will be returned. This internally will set the totp\_locked (pvt\_google\_auth\_secret\_locked) if successful.
##### Body parameter
```json
{
"token": "string",
"username": "niccolo@paganini.it"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successfully enrolled. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Provided MFA token does not match secret or other error | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
###### Enumerated Values
| Property | Value |
| --- | --- |
| user\_type | admin |
| user\_type | user |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"token": "string",
"username": "niccolo@paganini.it"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/mfa/enroll',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"user_properties": {
"requires_mfa_enrollment": true,
"user_type": "admin",
"mfa_secret": "string",
"allowed_profiles": [
"autologin"
],
"enforce_strong_passwords": true,
"allow_password_change": true
},
"username": "string",
"auth_token": "string",
"expires_after": "string",
"renewable_until": "string"
}
```
### client-import-api
The endpoints which are used on OpenVPN Access Server to import profiles into OpenVPN clients
#### get\_\_GetInstallerViaToken
`GET /GetInstallerViaToken`
This endpoint is one of endpoints of a simple REST api, that supports to fetch client configuration file from Access server. This endpoint is used to download installer file for client from Access Server. This endpoints requires authentication as string-token that can be obtained from the installer-url endpoint.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with installer file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC style errors response. Some of the older API under /rest are using error responses in the form of XMLRPC error. For compatibility reasons, these endpoints continue to use this way of reporting errors | Inline |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | “An error occurred while trying to download OpenVPN Connect from the server. The required client installer file was not found on the server” or another constant error in the case of unhandled error “Failed to download installer” | None |
```javascript
const headers = {
'Accept':'application/octet-stream'
};
fetch('/api/GetInstallerViaToken?token=string&installer_type=win_v3',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### get\_\_GetProfileViaToken
`GET /GetProfileViaToken`
This endpoint is one of endpoints of Web Services API called REST - the api, that supports to fetch client configuration file from Access server. Note that it is different from webapi/v1/api endpoints from that perspective that it still accepts any HTTPS client tool in usage, but unlike Client Web Service, it does not support full UI/UX design for Access Server. However Web Services API REST may respond with minimal html page. Some endpoints of this API require authentication as string-token, like this endpoint, in particular. See more about token in ProfileDownloadToken schema description.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with connection profile file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC style errors response. Some of the older API under /rest are using error responses in the form of XMLRPC error. For compatibility reasons, these endpoints continue to use this way of reporting errors | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetProfileViaToken?token=string',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
#### get\_\_GetAutologin
`GET /GetAutologin`
This endpoint allows a client to download an autologin profile (an OpenVPN profile without `--auth-user-pass`) with basic authentication. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with connection profile file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC style errors response. Some of the older API under /rest are using error responses in the form of XMLRPC error. For compatibility reasons, these endpoints continue to use this way of reporting errors | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetAutologin',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
#### get\_\_GetUserlogin
`GET /GetUserlogin`
This endpoint allows a client to download an userlogin profile (a profile requiring user/passwsord on connect `--using auth-user-pass`) with basic authentication. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with connection profile file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC style errors response. Some of the older API under /rest are using error responses in the form of XMLRPC error. For compatibility reasons, these endpoints continue to use this way of reporting errors | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetUserlogin',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
#### get\_\_GetGeneric
`GET /GetGeneric`
This endpoint allows a client to download a generic profile (a profile that is not tied to a specific user) with basic authentication. See also https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#rest-profile-download-api.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Responds with connection profile file | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | An XMLRPC style errors response. Some of the older API under /rest are using error responses in the form of XMLRPC error. For compatibility reasons, these endpoints continue to use this way of reporting errors | Inline |
```javascript
const headers = {
'Accept':'application/x-openvpn-profile'
};
fetch('/api/GetGeneric',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```markup
Invalid Request
REST method failed
No permission to generate profile (9422)
```
### profiletoken
APIs that manage the profile token that can be used to generate one time import URLs and are also used as part of the web-based profile import flow
#### bulktokenurldelete
`POST /token-url/delete`
deletes multiple tokens. Will only remove tokens if all ids are found.
##### Body parameter
```json
[
"string"
]
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | array\[string\] | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | token were successfully deleted | None |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | token to be deleted was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '[
"string"
]';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url/delete',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
### profile
APIs that are related to the management of client profiles
#### head\_\_openvpn-api\_profile
`HEAD /openvpn-api/profile`
This endpoint is used primarily by the OpenVPN clients to check if web-based login approach should be used to import profiles. See the OpenVPN webauth API specification https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md#detection-of-web-based-profile-download-support for full details.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Redirect to http://server\_addres/ page with saml headers in response according to OpenVPN Api spec. | None |
```javascript
fetch('/api/openvpn-api/profile',
{
method: 'HEAD'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 302 | Ovpn-WebAuth | string | | Token identifying if Web Auth is used, based on which connect app decides, if to open browser-based import flow |
This operation does not require authentication
#### get\_\_openvpn-api\_profile
`GET /openvpn-api/profile`
This endpoint is different from /api endpoints and is used by the OpenVPN client It is not used by the web UI, but redirects to UI login page instead according to the OpenVPN Api spec (https://github.com/OpenVPN/openvpn3/blob/master/doc/webautha.md#detection-of-web-based-profile-download-support).
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Redirect to http://server\_addres/login?relay\_state=profile | None |
This operation does not require authentication
```javascript
fetch('/api/openvpn-api/profile',
{
method: 'GET'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### getprofilesuser
`POST /profiles/list`
provides a list of all profiles of the user
##### Body parameter
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"user": {
"operation": "substring",
"value": "vio"
},
"serial_number": {
"value": 400,
"operation": "less_than"
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [profileRequestParameters](https://openvpn.net/as-docs/rest-api/#profilerequestparameters-1) | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| » profiles | \[allOf\] | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails-1) | false | none | none |
| »»» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1)(int64) | true | none | A serial number representing a certificate or profile. Note, this API uses strings for the certificate serial numbers instead of integers as JavaScript is unable to (easily) handle anything larger than 52 bit integers due to its nature to represent all numbers as double. |
| »»» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname-1) | true | none | The common name of the certificate. |
| »»» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm-1) | true | none | This specifies the algorithm to use a for a private/public keypair for X509 certificate generation. This is a identifier of the algorithm like ecp384r1, secp256r1 or secp512r1. For algorithm with variable key length the length is appended to the algorithm (e.g. rsa3072). |
| »»» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »»» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »»» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »»» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »»» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | A profile for a user. |
| »»» device\_id | string,null | false | none | Device ID, only used for server-locked v1 profiles |
| »»» comment | string,null | false | none | A user-defined comment |
| »»» profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | false | none | none |
| »»» tls\_crypt\_v2 | boolean | false | none | This profile uses tls-crypt-v2 |
| »»» last\_used | string,null(date) | false | none | Last date this profile was used (only date is known, there is no more granular resolution) |
| »»» username | string | false | none | User’s name |
###### Enumerated Values
| Property | Value |
| --- | --- |
| profile\_type | autologin |
| profile\_type | userlogin |
| profile\_type | generic |
| profile\_type | epki-generic |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"user": {
"operation": "substring",
"value": "vio"
},
"serial_number": {
"value": 400,
"operation": "less_than"
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/list',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"total": 0,
"profiles": [
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"device_id": "string",
"comment": "My toaster running Doom",
"profile_type": "autologin",
"tls_crypt_v2": true,
"last_used": "2019-08-24",
"username": "string"
}
]
}
```
#### generateUserProfile
`POST /profiles/create`
##### Body parameter
```json
{
"user": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [profileRequest](https://openvpn.net/as-docs/rest-api/#profilerequest-1) | false | none |
| » user | body | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | true | none |
| » tls\_crypt\_v2 | body | boolean | false | The client is capable of TLS-Crypt v2 |
| » comment | body | string | false | A user-defined comment |
| » ignore\_missing\_user | body | any | false | if this is flag, which requires admin rights, is set, a profile will be created even if the specified user does not exist. |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Profile was successfully generated | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | profile creation was not permitted | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Headers
| Status | Header | Type | Format | Description |
| --- | --- | --- | --- | --- |
| 201 | Content-Disposition | string | | none |
| 201 | VPN-Session-User | string | | none |
| 201 | VPN-Session-Token | string | | none |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"user": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/x-openvpn-profile',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### generateTokenUrl
`POST /token-url`
provides a token URL that can be used to generate a profile for a user or create an openvpn-import:// URL
##### Body parameter
```json
{
"lifetime": 0,
"usages": 0,
"profile_type": "autologin",
"username": "niccolo@paganini.it"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [tokenRequestParameters](https://openvpn.net/as-docs/rest-api/#tokenrequestparameters-1) | false | none |
| » lifetime | body | integer | false | Optional lifetime in seconds that the token should be valid for. Longer lifetimes than default require admin privileges. |
| » usages | body | integer | false | Optional number of usages that this token can be used to generate a profile. Defaults to a single use if not provided. Specifying more than more usage requires admin privileges. |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | true | none |
| » username | body | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Token URL has been successfully generated | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Token url was not generated | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"lifetime": 0,
"usages": 0,
"profile_type": "autologin",
"username": "niccolo@paganini.it"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### enumerateTokenIds
`GET /token-url/list`
return all known and valid tokenIDs for token urls. This will always return all token-urls and there is no filters implemented in this API.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | list of all still valid profile token urls | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » profileTokens | \[[profileToken](https://openvpn.net/as-docs/rest-api/#profiletoken-3)\] | false | none | \[this represent a (typically one-time) token that can be used to retrieve a profile from Access Server\] |
| »» token | string | false | none | the unique string that identifies the token |
| »» username | string | false | none | the username this token will generate the profile for |
| »» expires | string(date-time) | false | none | the token is only valid until this time |
| »» profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | false | none | none |
| »» usages | integer | false | none | how often this token can be used to retrieve a profile |
###### Enumerated Values
| Property | Value |
| --- | --- |
| profile\_type | autologin |
| profile\_type | userlogin |
| profile\_type | generic |
| profile\_type | epki-generic |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/token-url/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"profileTokens": [
{
"token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
"username": "arne@openvpn.net",
"expires": "2019-08-24T14:15:22Z",
"profile_type": "autologin",
"usages": 1
}
]
}
```
#### deleteProfileSerial
`POST /profiles/delete/{serial}`
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| serial | path | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1) | true | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | profile successfully deleted | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | could not delete the profile | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | string | false | none | describes status of deletion |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete/{serial}',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": "string"
}
```
#### deleteProfileUser
`POST /profiles/delete-user`
##### Body parameter
```json
{
"users": [
"niccolo@paganini.it"
],
"filter": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » users | body | \[[username](https://openvpn.net/as-docs/rest-api/#username-1)\] | false | users name list to delete connection profiles from. |
| » filter | body | string | false | will delete all profiles that have the argument as a substring |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | profile successfully deleted | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | User profiles were not deleted | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | User profiles were not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | string | false | none | describes status of deletion |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"users": [
"niccolo@paganini.it"
],
"filter": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete-user',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": "string"
}
```
#### deleteProfile
`POST /profiles/delete`
##### Body parameter
```json
[
"1708464983752887'"
]
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1) | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successfully executed. Status for each profile is in the response. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | could not delete the profile | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » message | any | false | none | describes status of deletion |
| » response | object | true | none | hash map that maps the requested delete request to a result |
| »» **additionalProperties** | [profileDeleteCode](https://openvpn.net/as-docs/rest-api/#profiledeletecode) | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **additionalProperties** | {“204”:null,“description”:“profile successfully deleted”} |
| **additionalProperties** | {“404”:null,“description”:“profile to be deleted was not found”} |
| **additionalProperties** | {“403”:null,“description”:“profile to be deleted is not owned by the user or another error”} |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '[
"1708464983752887'"
]';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/profiles/delete',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"message": null,
"response": {
"21": 204,
"7127317": 404
}
}
```
### vpnca
endpoints that manage the CA(s) that is used to sign the VPN server certificate and the client certificates
#### getVPNCas
`GET /ca/vpn/list`
returns a list of all certificate authorities
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[allOf\] | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails-1) | false | none | none |
| »» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1)(int64) | true | none | A serial number representing a certificate or profile. Note, this API uses strings for the certificate serial numbers instead of integers as JavaScript is unable to (easily) handle anything larger than 52 bit integers due to its nature to represent all numbers as double. |
| »» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname-1) | true | none | The common name of the certificate. |
| »» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm-1) | true | none | This specifies the algorithm to use a for a private/public keypair for X509 certificate generation. This is a identifier of the algorithm like ecp384r1, secp256r1 or secp512r1. For algorithm with variable key length the length is appended to the algorithm (e.g. rsa3072). |
| »» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
| »» cert\_type | [certificateType](https://openvpn.net/as-docs/rest-api/#certificatetype) | true | none | The type of certificate. |
| »» client\_profiles | integer | true | none | the number of VPN client profiles are issued by this CA. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| cert\_type | ca |
| cert\_type | old\_ca |
| cert\_type | cross\_ca |
| cert\_type | client |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"cert_type": "ca",
"client_profiles": 0
}
]
```
#### addCaGeneration
`POST /ca/vpn/create`
Will add a new CA and also setup proper cross-signed certificates for the new CA.
##### Body parameter
```json
{
"algorithm": "secp384r1",
"common_name": "my shiny new CA"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [certificateRequest](https://openvpn.net/as-docs/rest-api/#certificaterequest-1) | false | none |
| » algorithm | body | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm-1) | false | This specifies the algorithm to use a for a private/public keypair for X509 certificate generation. This is a identifier of the algorithm like ecp384r1, secp256r1 or secp512r1. For algorithm with variable key length the length is appended to the algorithm (e.g. rsa3072). |
| » common\_name | body | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname-1) | false | The common name of the certificate. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | New CA has been successfully created | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | the selected algorithm is not allowed or the common is too long or contains invalid characters or already exists | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"algorithm": "secp384r1",
"common_name": "my shiny new CA"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "config values had errors",
"detail": {
"host.name": "Contains invalid character %",
"server.port": "Must be an integer between 1 and 65335"
}
}
```
#### delete\_**ca\_vpn**{serial}
`DELETE /ca/vpn/{serial}`
Will delete a VPN certificate authority. unless the delete\_clients parameter is given, this method will fail if there are still client certificate that use this CA.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | CA has been successfully deleted | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | the CA has still client certificates or is the only CA | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | The CA to be deleted is not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/vpn/{serial}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| serial | path | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1) | true | none |
| delete\_clients | query | boolean | false | will force the deletion of the CA (and all client certificates) |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### CaSupportedAlgorithms
`GET /ca/allowed-algorithms/list`
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[[certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm-1)\] | false | none | \[This specifies the algorithm to use a for a private/public keypair for X509 certificate generation. This is a identifier of the algorithm like ecp384r1, secp256r1 or secp512r1. For algorithm with variable key length the length is appended to the algorithm (e.g. rsa3072).\] |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/ca/allowed-algorithms/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
"rsa2048",
"rsa3072",
"rsa4096",
"ed448",
"brainpoolP384r1",
"brainpoolP512r1",
"secp2256k1",
"Ed25519"
]
```
### info
endpoints that allow to query various aspects of the running server and its status
#### certificateInfo
`POST /certificate/info`
This parses a PEM encoded certificate and provides information about its properties as results. This method is restricted to admin users to avoid exploitation in case there is some bug in the backend’s X509 parser. This can be used to display additional information for configuration items where the value is an X509 certificate (e.g. SAML and web certificates).
##### Body parameter
```json
{
"certificate": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » certificate | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate-1)(pem) | false | An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—– |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | information about the X509 certificate | [certificateInformationDetails](https://openvpn.net/as-docs/rest-api/#certificateinformationdetails-1) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | the provided certificate could not be parsed or other problems. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"certificate": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/info',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"sha256fp": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"subj_alt_names": [
"DNS:foo.example.com",
"DNS:www.openvpn.net",
"IP:1.2.3.4"
],
"subject": [
"C=US",
"ST=Maryland",
"L=Pasadena",
"O=DevOrg",
"OU=FreeSoft",
"OU=non-free soft",
"CN=rogue software department"
],
"ca": true
}
```
#### checkPrivateKey
`POST /certificate/check-private-key`
This parses the PEM certificate in certificate and checks if the private key provided in pkey matches the certificate. Either the private key has to be provided with the private\_key attribute or with the config\_key and the backend will then read the content from that key
##### Body parameter
```json
{
"certificate": "string",
"private_key": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Can parse both private key and certificate. The content will signal if the private key belongs to the certificate. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | there was some error parsing the certificate or key | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » status | boolean | false | none | true if the private key matches the certificate |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"certificate": "string",
"private_key": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/check-private-key',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"status": true
}
```
#### post\_\_certificate\_check-against-ca-roots
`POST /certificate/check-against-ca-roots`
checks the certificate against a provided collection of CA certificate or if left empty a builtin collection of common CAs that are used by browsers and operating systems. It will assume that the certificate(s) in chain are part of the required certificate chain. The function will first check that certificate and chain build a chain by checking if each certificates in chain signs the previous and then ultimately if the last certificate or second-to-last certificate of the chain is signed by one of the CAs in `ca_roots`. This checking both the last and second-to-last certificate is done since ca chains that are provided very commonly contains the CA itself or lack it. Note this function **only** establishes if there is a path that lead from the certificate to one of the root CAs. It does not check any other requirement that certificate typically have to considered valid. This includes but is not limited to checking if the certificates in the chain are intermediate CAs that are actually allowed to sign certificates, the keyUsage and extendedKeyUsage of the involved certificates or revocation. If the certificate contains multiple certificate the first certificate is considered to be the certificate to be checked and the other ones are considered to be intermediate certificates of the certificate chain and are treated the same way as the certificate(s) in the chain property.
##### Body parameter
```json
{
"certificate": "string",
"chain": "string",
"ca_roots": [
"string"
]
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The certificate has been verified against the provided CA certificate as trusted certificate. The response contains the trust chain that was found. | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | The certificate failed verification. Details are provided in the errorReason. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const inputBody = '{
"certificate": "string",
"chain": "string",
"ca_roots": [
"string"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/certificate/check-against-ca-roots',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"chain": [
{
"serial": "1708464983752887'",
"common_name": "OpenVPN VPN server CA",
"algorithm": "rsa2048",
"not_before": "2020-03-27",
"not_after": "2030-03-26",
"self_signed": true,
"signing_ca": "123",
"signing_ca_cn": "RootCA",
"sha256fp": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"subj_alt_names": [],
"subject": [],
"ca": true
}
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » certificate | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate-1)(pem) | true | An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—– |
| » chain | body | [pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate-1)(pem) | false | An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—– |
| » ca\_roots | body | \[[pemEncodedCertificate](https://openvpn.net/as-docs/rest-api/#pemencodedcertificate-1)\] | false | a list of CA certificates that should be used as trusted certificate authorities. If left empty AS will use the system certificates root CAs. This are very similar but not always identical to a browser trust store. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » chain | \[allOf\] | false | none | \[Provides more information about a certificate\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [certificateDetails](https://openvpn.net/as-docs/rest-api/#certificatedetails-1) | false | none | none |
| »»» serial | [certificateSerial](https://openvpn.net/as-docs/rest-api/#certificateserial-1)(int64) | true | none | A serial number representing a certificate or profile. Note, this API uses strings for the certificate serial numbers instead of integers as JavaScript is unable to (easily) handle anything larger than 52 bit integers due to its nature to represent all numbers as double. |
| »»» common\_name | [certificateCommonName](https://openvpn.net/as-docs/rest-api/#certificatecommonname-1) | true | none | The common name of the certificate. |
| »»» algorithm | [certificateAlgorithm](https://openvpn.net/as-docs/rest-api/#certificatealgorithm-1) | true | none | This specifies the algorithm to use a for a private/public keypair for X509 certificate generation. This is a identifier of the algorithm like ecp384r1, secp256r1 or secp512r1. For algorithm with variable key length the length is appended to the algorithm (e.g. rsa3072). |
| »»» not\_before | string(date-time) | true | none | Earliest time the certificate is valid |
| »»» not\_after | string(date-time) | true | none | Latest time the certificate is valid |
| »»» self\_signed | boolean | false | none | Whether this certificate is self-signed. Typically only root CA certificates are self-signed. |
| »»» signing\_ca | string(int64) | false | none | The certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. This is also represented as a string rather than integer to avoid problems with JavaScript numbers always being double. |
| »»» signing\_ca\_cn | string | false | none | The common name of certificate authority that has signed this certificate. For self-signed certificate authorities this value is absent. This attribute is only present for certificates that are managed by the internal PKI of Access Server and the APIs that deal and return information about these. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» sha256fp | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint-1)(sha256) | false | none | The SHA256 hash of the certificate body, also known as the fingerprint of the certificate. |
| »»» subj\_alt\_names | \[string\] | false | none | provides a list of the subjectAlternative attributes of the certificate |
| »»» subject | \[string\] | false | none | the full subject of the certificate and not only the CN |
| »»» ca | boolean | false | none | Whether the certificate represents a certificate authority |
| »»» self\_signed | boolean | false | none | the signature of the certificate is valid against its own public key |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### get\_\_eula
`GET /eula`
get the current current end user license agreement (EULA) and the status of the user accepting it. The eula is considered accepted if the variable aui.eula\_version has the same value as the Eula version returned by this API.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Provides the current EULA and the status of the user accepting it. | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/eula',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"eula": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
"eula_web": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
```
##### Response Schema
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### serverInterfaces
`GET /server/interfaces`
gets the current interfaces and the IP addresses of these interfaces
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| no\_loopback | query | boolean | false | optionally for excluding localhost |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | A list of Ethernet interfaces and assigned IP/IPv6 addresses | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | \[[serverInterface](https://openvpn.net/as-docs/rest-api/#serverinterface-1)\] | false | none | \[describes a Linux network interface and the associated primary networks\] |
| » name | any | false | none | the name identifying the interface |
| » networks | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet-1)\] | false | none | IP addresses assigned to the interface |
| »» ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| »» netip | string | false | none | the network IP address. |
| »» prefix\_length | integer | false | none | length of the prefix in CIDR notation |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/interfaces',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
[
{
"name": "eth0",
"networks": [
{},
{},
{}
]
}
]
```
#### get\_\_server\_info
`GET /server/info`
provides a summary of various run time status of Access Server
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Information about the running Access Server instance | [serverInfo](https://openvpn.net/as-docs/rest-api/#serverinfo-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/info',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": [
"27"
],
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"os_hostname": "access-server-os-hostname"
}
```
#### get\_\_vpn\_dco-module
`GET /vpn/dco-module`
checks if the DCO kernel module is available and what version the module is.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | DCO Module status | [dcoModuleStatus](https://openvpn.net/as-docs/rest-api/#dcomodulestatus) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/dco-module',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"available": true,
"version": "0.2.20230323"
}
```
#### post\_\_helper\_status-overview
`POST /helper/status-overview`
this operation combines multiple individual calls to avoid multiple calls to the API for displaying the initial status overview page. It will combine a request to /config-items/{configurationProfile}/list with {profile} being active profile, a /server/info and a /vpn/dco-module response. It will also indicate the latest version of the EULA and if this version has been accepted by the user.
##### Body parameter
```json
{
"names": [
"vpn.server.cipher"
]
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Something went wrong | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const inputBody = '{
"names": [
"vpn.server.cipher"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/helper/status-overview',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"configuration_items": {
"total": 0,
"items": [
{}
]
},
"server_info": {
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": [
"27"
],
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"os_hostname": "access-server-os-hostname"
},
"dco_module": {
"available": true,
"version": "0.2.20230323"
},
"eula_status": {
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » names | body | \[[configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey-1)\] | false | list of configuration items that should be retrieve from the active configuration |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » configuration\_items | object | false | none | Response from the /config/{activeprofile}/items part of the query |
| »» total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| »» items | \[allOf\] | false | none | \[This represents a configuration item in the server configuration profile. To determine if this item has been user-set or not, check the value of derived\_from.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | object | false | none | none |
| »»»» name | [configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey-1) | true | none | the configuration value’s key. |
| »»»» derived\_from | [configurationValueSource](https://openvpn.net/as-docs/rest-api/#configurationvaluesource-1) | true | none | the source that the current values has be derived from. |
| »»»» type | string | false | none | Determines the value type of this configuration item. This also implies which of the different value attributes are expected to be present on this configuration item. |
| »»»» description | string | false | none | A user readable description of the configuration item that gives a user an understandable. This item can be absent for custom configuration values. |
| »»»» category | string | true | none | Different items have different visibility/category that should be taken into account when presenting them to the user. This key informs the UI if a variable is deprecated but still evaluated (deprecated), deprecated and removed (removed), normal, advanced (a value that for normal operation of OpenVPN Access Server should need to be changed as it is typically reserved for some corner-case or speciality configurations) or is a calculated value that is readonly as it is calculated from other configuration items but is not modifiable by the user (derived). Items that have a type of required often do not have a default value but must be set in order for Access to correctly work (e.g. host.name). Removed values should be only shown by the UI if the are set by the user. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | any | false | none | none |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [integerConfigurationValue](https://openvpn.net/as-docs/rest-api/#integerconfigurationvalue-1) | false | none | A configuration value that is expressed as an integer. |
| »»»»» value | integer | false | none | none |
| »»»»» default\_value | integer | false | none | The default value for the configuration. |
| »»»»» max\_value | integer | false | none | A hint of maximum allowed value |
| »»»»» min\_value | integer | false | none | A hint for minimum allowed value |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [booleanConfigurationValue](https://openvpn.net/as-docs/rest-api/#booleanconfigurationvalue) | false | none | none |
| »»»»» value | boolean | false | none | none |
| »»»»» default\_value | boolean | false | none | The default value for the configuration. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [stringConfigurationValue](https://openvpn.net/as-docs/rest-api/#stringconfigurationvalue-1) | false | none | A configuration value that is expressed as a string. Either value or redacted\_value is present |
| »»»»» value | string | false | none | the value of this string configuration |
| »»»»» redacted\_value | string | false | none | the real value of this configuration key is not present because it is a private key or password. The value of this string will give an indication of the redacted value. |
| »»»»» default\_value | string | false | none | The default value for the configuration. |
| »»»»» allowed\_values | \[string\] | false | none | if present this array has a list of the allowed values |
| »»»»» type\_hint | string | false | none | if present, this type hint denotes this configuration value to contain a special type of value, so the UI can do additional verification to ensure the user input matches this type |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» **anonymous** | [customConfigurationValue](https://openvpn.net/as-docs/rest-api/#customconfigurationvalue-1) | false | none | This is a configuration value for which the backed does have no information. This is likely a custom configuration key that a user manually entered or a configuration value that is a result from a downgrade and is only present in newer Access Server versions. |
| »»»»» value | string | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » server\_info | [serverInfo](https://openvpn.net/as-docs/rest-api/#serverinfo-1) | false | none | none |
| »» version | string | false | none | the version number of Access Server |
| »» build | string | false | none | the build of Access Server. |
| »» web\_version | string | false | none | the build version number of Access Server UI |
| »» web\_override | boolean | false | none | if true the version of the web ui that is used comes from an override-web.zip instead of the bundled version |
| »» client\_version | string | false | none | version of the embedded client package |
| »» os\_distribution | string | false | none | a human readable identifier of the current (Linux) distribution like PRETTY\_NAME from /etc/os-release |
| »» architecture | string | false | none | the CPU architecture |
| »» cores | integer | false | none | the number of cores visible to the operating system |
| »» os\_hostname | string | false | none | Operating system’s hostname |
| » dco\_module | [dcoModuleStatus](https://openvpn.net/as-docs/rest-api/#dcomodulestatus) | false | none | none |
| »» available | boolean | true | none | whether AS detected an installed and working data channel offloading kernel module |
| »» version | string | true | none | version of the module if available |
| » eula\_status | [eulaStatus](https://openvpn.net/as-docs/rest-api/#eulastatus) | false | none | none |
| »» eula\_version\_as | integer | false | none | The version of the AS EULA |
| »» eula\_web\_hash | string(sha256) | false | none | A SHA256 string in hex format without : separators |
| »» eula\_accepted | boolean | false | none | indicates whether the config setting (aui.eula\_version) has the same value as eula\_version\_as |
###### Enumerated Values
| Property | Value |
| --- | --- |
| derived\_from | default |
| derived\_from | local\_db |
| derived\_from | cluster\_db |
| derived\_from | mysql\_standalone\_db |
| derived\_from | as\_conf |
| derived\_from | environment |
| derived\_from | runtime |
| derived\_from | other |
| type | custom |
| type | integer |
| type | boolean |
| type | string |
| category | deprecated |
| category | removed |
| category | normal |
| category | required |
| category | derived |
| category | advanced |
| category | custom |
| type\_hint | ipv4Address |
| type\_hint | ipv6Address |
| type\_hint | ipAddress |
| type\_hint | hostname |
| type\_hint | pemCertificate |
| type\_hint | pemPrivateKey |
| architecture | arm64 |
| architecture | amd64 |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
### license
APIs that allow examining and setting licensing of the AS instance
#### licenseInfo
`GET /license/info`
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | the current status of the access Server licensing | [licenseInfo](https://openvpn.net/as-docs/rest-api/#licenseinfo-3) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/info',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"licensing_type": "unlicensed",
"current_cc": 3,
"max_cc": 13,
"fixed_licenses": [
{
"expiry": "2019-08-24T14:15:22Z",
"key": "string",
"max_cc": 0
}
]
}
```
#### checkSubscription
`POST /license/subscription/test`
will try to use the subscription against and report back the results from the test. This will not configure AS to use the subscription.
##### Body parameter
```json
{
"subscription": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » subscription | body | string | true | The subscription file. This is either a string containing a json object or a base64 encoding of the json object. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The result of the subscription test | [subscriptionInfo](https://openvpn.net/as-docs/rest-api/#subscriptioninfo-1) |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | format the license is not detected or other error with license. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"subscription": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription/test',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"agent_id'": "13014502862141447248",
"agent_disabled": true,
"cc_limit": 13,
"error": "string",
"fallback_cc'": 2,
"grace_period": 30,
"last_successful_update": "2019-08-24T14:15:22Z",
"total_cc": 0,
"name": "Test subscription for development",
"subkey": "ASUYHgkSWvVQFZhJXVdgtEa_AStctYuHirYZeFbZjLvQCWCaViVamXwL_7a289be35f6987c9aec4585c922a740c1b7620d5",
"billing_id": "tctYuHirYZeFbZjLvQC",
"next_update": "2019-08-24T14:15:22Z",
"updates_failed": 0,
"notes": [
"Subscription will expire on 1/2/3",
"Maximum allowed concurrent connections might be limited to 23 by the 'subscription.local_cc_limit' setting"
],
"overdraft": true,
"server": "asb.sts.openvpn.net",
"type": "-",
"state": "SUBSCRIPTION_OK"
}
```
#### loadSubscription
`POST /license/subscription`
Will instruct Access to use the license/subscription. This will not verify that the subscription file is actually valid. Use the the /license/subscription/test API end point to check if the subscription is valid before using this end point. This will also overwrite an existing subscription.
##### Body parameter
```json
{
"subscription": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » subscription | body | string | true | The subscription file. This is either a string containing a json object or a base64 encoding of the json object. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Subscription has been successfully loaded. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | format the license is not detected or other error with license. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"subscription": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### deactivateSubscription
`DELETE /license/subscription`
delete/unconfigures the currently active subscription
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Subscription has been successfully deactivated. | None |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/subscription',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### activateFixedLicenseOnline
`POST /license/fixed-license/online-activation`
Will instruct Access to use the license. This will verify that the license is actually valid.
##### Body parameter
```json
{
"license": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » license | body | string | true | The license file |
###### format the license is not detected or other error with license.
```json
{
"message": "License not found on server"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Online license has been successfully activated. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | format the license is not detected or other error with license. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"license": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/fixed-license/online-activation',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### activateFixedLicenseOffline
`POST /license/fixed-license/offline-activation`
Will instruct Access to use the license. This will verify that the license is actually valid.
##### Body parameter
```yaml
license: string
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » license | body | string | true | The license file |
###### format the license is not detected or other error with license.
```json
{
"message": "Fixed license already expired"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Fix license has been successfully activated. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | format the license is not detected or other error with license. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"license": "string"
}';
const headers = {
'Content-Type':'multipart/form-data',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/fixed-license/offline-activation',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### licenseGetMachineId
`GET /license/machine-id`
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | machine id file is returned | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'text/plain',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/license/machine-id',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```
"string"
```
### proxy
pseudo endpoint that explains the proxying mechanism to reach other AS backend servers in a clustered OpenVPN Access Server setup.
#### post\_\_proxy
`POST /proxy`
\< This is not a real API endpoint. Rather it serves as a workaround to document a feature in OpenVPN Access Server that otherwise would be impossible to document apart from adding/copying pasting the same properties and responses and so on to all endpoints. (Almost) all endpoints will support this mechanism of proxying. When the middleware receives a request for any endpoint with the X-OpenVPN-AS-Node as additional header in it, it will check if the host is one of the names of the backend servers. See the /cluster/nodes/list endpoint for retrieving all backend servers. The request will then be proxied to the specified backend node and the the answer will be proxied back. The proxy request to the other backend will contain also the X-Forwarded-For header with the information of the client and the X-Forwarded-Host header that contains the name of the node that did the forward. If a node gets a request that has its own name in the X-Forwarded-Host, this request has been in a loop (most likely wrong dns/host configuration in the cluster database) and should return an error instead of trying to proxy it again. Because this is a different connection, the error reporting is sometimes a bit different if there is a connection problem. The middleware will not check authentication or do other checks on the request aside from ensuring that the target is in the list of backend servers. The responses documented here can occur in addition to the normal responses that can happen when calling an endpoint. The /cluster/
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 502 | [Bad Gateway](https://tools.ietf.org/html/rfc7231#section-6.6.3) | there was some communication problems with the other backend node other than a timeout or the host specified in the X-OpenVPN-AS-Node header is not in the list of backend servers. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 504 | [Gateway Time-out](https://tools.ietf.org/html/rfc7231#section-6.6.5) | Proxying to the other node timed out | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-AS-Node':'string',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/proxy',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| X-OpenVPN-AS-Node | header | string | false | This is an optional header that is used to determine the backend that this request should be redirected to. |
###### Detailed descriptions
**X-OpenVPN-AS-Node**: This is an optional header that is used to determine the backend that this request should be redirected to. Note this value of the name is the name of the node and not the api\_endpoint of the node. See the /proxy pseudo endpoint to get a description of this mechanism.
### cluster
APIs related to setting, querying status and managing an OpenVPN Access Server cluster
#### clusterListNodes
`GET /cluster/nodes/list`
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » nodes | object | false | none | holds a dictionary of all the nodes that are part of the cluster |
| »» **additionalProperties** | any | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [clusterNode](https://openvpn.net/as-docs/rest-api/#clusternode-1) | false | none | describes a node in the cluster. The certificate field is the certificate that the node will present on its api\_endpoint and that is expected to be used to verify the identity of the node. |
| »»»» name | string | true | none | the name that uniquely identifies the cluster node \[node\_name\] |
| »»»» api\_endpoint | [apiEndpoint](https://openvpn.net/as-docs/rest-api/#apiendpoint-1) | false | none | the API endpoint to specifically address a node. Requires format https:ip/hostname:port. Note that https is necessary because certificateFingerprint is used by https client to verify it is indeed talking to the right node. |
| »»»» certificate\_fingerprint | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint-1)(sha256) | false | none | The SHA256 hash of the certificate body, also known as the fingerprint of the certificate. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | object | false | none | none |
| »»»» restart\_pending | boolean | false | none | Indicates if a node has a pending restart. |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/nodes/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"nodes": {
"property1": {
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"restart_pending": true
},
"property2": {
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"restart_pending": true
}
}
}
```
#### rrdnshostname
`PUT /cluster/rr-dns-hostname`
Set host.name in confdb\_local, for all nodes in cluster, to rr\_dns\_hostname from clusterdb
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Setting the cluster properties failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/rr-dns-hostname',
{
method: 'PUT',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### clustergetprops
`GET /cluster/props`
Fetch props for the cluster from ClusterDB.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » props | object | false | none | holds a dictionary of all props of the cluster |
| »» **additionalProperties** | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops-1) | false | none | properties common to all nodes in the cluster. |
| »»» rr\_dns\_hostname | string | false | none | the Round-Robin hostname that uniquely identifies the cluster |
| »»» rr\_dns\_new\_nodes | boolean | false | none | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/props',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"props": {
"property1": {
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
},
"property2": {
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
}
}
```
#### clustersetprops
`POST /cluster/props`
Set props of the cluster in ClusterDB.
##### Body parameter
```json
{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops-1) | false | none |
| » rr\_dns\_hostname | body | string | false | the Round-Robin hostname that uniquely identifies the cluster |
| » rr\_dns\_new\_nodes | body | boolean | false | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
###### Setting the cluster properties failed
```json
{
"message": "rr_dns_hostname has invalid characters in it"
}
```
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Properties on the cluster node have been successfully set. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Setting the cluster properties failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/props',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### clusterset
`POST /cluster/{node}/set`
set parameters of a cluster node. This is an atomic operation that either set all parameters or none. This takes a clusterNode object and will set only the properties that are defined on that object.
##### Body parameter
```json
{
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| node | path | string | true | none |
| body | body | object | false | none |
| » api\_endpoint | body | [apiEndpoint](https://openvpn.net/as-docs/rest-api/#apiendpoint-1) | false | the API endpoint to specifically address a node. Requires format https:ip/hostname:port. Note that https is necessary because certificateFingerprint is used by https client to verify it is indeed talking to the right node. |
| » certificate\_fingerprint | body | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint-1)(sha256) | false | The SHA256 hash of the certificate body, also known as the fingerprint of the certificate. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Properties on the cluster node have been successfully set. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Error setting the cluster properties failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/{node}/set',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"invalidchars": {
"value": {
"message": "api_endpoint has invalid characters in it"
}
}
}
```
#### post\_\_cluster\_join
`POST /cluster/join`
Instructs the standalone Access Server instance to join a cluster. The cluster must already be set up. already existing Access Server. If the fingerpint is not provided in the join request the node will calculate the fingerprint.
##### Body parameter
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | joining the cluster failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/join',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterNodeJoinRequest](https://openvpn.net/as-docs/rest-api/#clusternodejoinrequest-1) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### post\_\_cluster\_create
`POST /cluster/create`
Instructs the Access Server instance to create a new cluster. This will use the current configuration as a basis for the new cluster wide databases and configuration. Creating a cluster will also make the current node member of that cluster.
##### Body parameter
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/",
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | creating the cluster failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/",
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/create',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [clusterNodeCreateRequest](https://openvpn.net/as-docs/rest-api/#clusternodecreaterequest-1) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
#### post\_\_cluster\_leave
`POST /cluster/leave`
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation. Leaving the cluster succeeded | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | leaving the cluster failed | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/cluster/leave',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### put\_\_database\_convert
`PUT /database/convert`
Converts local SQLite databases to MySQL databases and updates as.conf to use converted databases. Note that a cold restarts AS is required so AS can reload as.conf after a full restart.
##### Body parameter
```json
{
"mysqluri": "mysql://user:password@mysql.example.com:3306/"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Converting the database failed. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"mysqluri": "mysql://user:password@mysql.example.com:3306/"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/database/convert',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » mysqluri | body | [mysqluri](https://openvpn.net/as-docs/rest-api/#mysqluri) | false | the URI of the mysql server. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
### maintenance
APIs used for server maintenance like restarting.
#### get\_\_support\_report
`GET /support/report`
generates the report of the Access Server Support that includes most requested information for to help troubleshooting. Note only call this API when necessary as it is quite heavy on the server side for collecting information as it involves executing external programs and also might take a bit of time to execute.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | The report that is also generated by ‘sacli support’ | string |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'text/plain',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/support/report',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```
"string"
```
#### post\_\_server\_restart
`POST /server/restart`
instructs the backend to be restarted
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Server restart successfully scheduled | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Server has some misconfiguration and restart is not scheduled | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/restart',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| restartMode | query | [restartMode](https://openvpn.net/as-docs/rest-api/#restartmode-1) | false | none |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| restartMode | cold |
| restartMode | warm |
| restartMode | dry\_run |
| restartMode | systemctl |
| restartMode | server\_agent |
#### serverStatus
`GET /server/status`
gets the current status of the server and status of the individual service similar to `sacli Status`
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | the server status | [serverStatus](https://openvpn.net/as-docs/rest-api/#serverstatus-3) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | User does not have admin permission | None |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/server/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"last_restarted": "2019-08-24T14:15:22Z",
"service_status": {
"property1": {
"status": "on",
"error": []
},
"property2": {
"status": "on",
"error": []
}
},
"auth_module_status": {
"property1": "on",
"property2": "on"
}
}
```
### configurationProfile
API to manage OpenVPN Access Server’s main configuration database
#### enumerateConfigurationProfileList
`GET /config-profile/list`
returns the currently active configuration profile name and a list of all profiles.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » active\_profile | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | false | none | This is the configuration profile name. A typical access server uses the DEFAULT profile as the normal profile. Multiple profiles can be used to make a backup or to first edit an inactive profile and then apply all changes at once. |
| » profiles | \[[configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3)\] | false | none | A list of all configuration profiles on Access Server |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/list',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"active_profile": "default",
"profiles": [
"default",
"heaven",
"hades",
"olymp"
]
}
```
#### configurationProfileDelete
`DELETE /config-profile/{profile}`
deletes a configuration profile if it exists and is not the active one
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | configuration profile successfully deleted | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | profile deletion would violate some constraints like deleting the active profile | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | configuration profile to be deleted was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### configurationProfileCreate
`POST /config-profile`
Creates a new configuration profile and optionally copies the initial values from an other profile if the copyFrom parameter is present. Otherwise the new configuration profile will be empty.
##### Body parameter
```json
{
"profile": "string",
"copy_from": "string"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | true | none |
| » profile | body | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | This is the configuration profile name. A typical access server uses the DEFAULT profile as the normal profile. Multiple profiles can be used to make a backup or to first edit an inactive profile and then apply all changes at once. |
| » copy\_from | body | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | false | This is the configuration profile name. A typical access server uses the DEFAULT profile as the normal profile. Multiple profiles can be used to make a backup or to first edit an inactive profile and then apply all changes at once. |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | configuration profile successfully created | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | profile creation has some problem like using an invalid profile name | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | configuration profile to be copied from was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"profile": "string",
"copy_from": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### validateConfigProfile
`GET /config-profile/{profile}/validate`
Validates a configuration profile and checks for errors
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success. No errors in the profile are detected | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | validation of the profile encountered some problems see the error reason for more details. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | configuration profile to be validated was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}/validate',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### RunSetActiveProfile
`POST /config-profile/{profile}/set-active`
Validates the profile and if it validates, it sets the named profile to be the active profile and restarts OpenVPN with the new profile in specified restart mode.
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| profile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
| restartMode | query | [restartMode](https://openvpn.net/as-docs/rest-api/#restartmode-1) | false | none |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| restartMode | cold |
| restartMode | warm |
| restartMode | dry\_run |
| restartMode | systemctl |
| restartMode | server\_agent |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success. No errors in the profile are detected and the new profile is being set. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | validation of the profile encountered some problems or some other error occurred. See error reason for more details. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | the requested configuration profile was not found. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-profile/{profile}/set-active',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### getConfigItems
`POST /config-items/{configurationProfile}/list`
fetches a list of specified configuration values or all if names is not given. The total amount for all item is limited by the number of available configuration options (\<500) in Access Server, so no pagination is provided in this API.
##### Body parameter
```json
{
"names": [
"vpn.server.cipher"
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| configurationProfile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | configuration profile to be listed was not found | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail-1) |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of profiles that match if pagination is not in effect, this matches the size of the provided array |
| » items | \[allOf\] | false | none | \[This represents a configuration item in the server configuration profile. To determine if this item has been user-set or not, check the value of derived\_from.\] |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [configurationItemKey](https://openvpn.net/as-docs/rest-api/#configurationitemkey-1) | true | none | the configuration value’s key. |
| »»» derived\_from | [configurationValueSource](https://openvpn.net/as-docs/rest-api/#configurationvaluesource-1) | true | none | the source that the current values has be derived from. |
| »»» type | string | false | none | Determines the value type of this configuration item. This also implies which of the different value attributes are expected to be present on this configuration item. |
| »»» description | string | false | none | A user readable description of the configuration item that gives a user an understandable. This item can be absent for custom configuration values. |
| »»» category | string | true | none | Different items have different visibility/category that should be taken into account when presenting them to the user. This key informs the UI if a variable is deprecated but still evaluated (deprecated), deprecated and removed (removed), normal, advanced (a value that for normal operation of OpenVPN Access Server should need to be changed as it is typically reserved for some corner-case or speciality configurations) or is a calculated value that is readonly as it is calculated from other configuration items but is not modifiable by the user (derived). Items that have a type of required often do not have a default value but must be set in order for Access to correctly work (e.g. host.name). Removed values should be only shown by the UI if the are set by the user. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | any | false | none | none |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [integerConfigurationValue](https://openvpn.net/as-docs/rest-api/#integerconfigurationvalue-1) | false | none | A configuration value that is expressed as an integer. |
| »»»» value | integer | false | none | none |
| »»»» default\_value | integer | false | none | The default value for the configuration. |
| »»»» max\_value | integer | false | none | A hint of maximum allowed value |
| »»»» min\_value | integer | false | none | A hint for minimum allowed value |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [booleanConfigurationValue](https://openvpn.net/as-docs/rest-api/#booleanconfigurationvalue) | false | none | none |
| »»»» value | boolean | false | none | none |
| »»»» default\_value | boolean | false | none | The default value for the configuration. |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [stringConfigurationValue](https://openvpn.net/as-docs/rest-api/#stringconfigurationvalue-1) | false | none | A configuration value that is expressed as a string. Either value or redacted\_value is present |
| »»»» value | string | false | none | the value of this string configuration |
| »»»» redacted\_value | string | false | none | the real value of this configuration key is not present because it is a private key or password. The value of this string will give an indication of the redacted value. |
| »»»» default\_value | string | false | none | The default value for the configuration. |
| »»»» allowed\_values | \[string\] | false | none | if present this array has a list of the allowed values |
| »»»» type\_hint | string | false | none | if present, this type hint denotes this configuration value to contain a special type of value, so the UI can do additional verification to ensure the user input matches this type |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»» **anonymous** | [customConfigurationValue](https://openvpn.net/as-docs/rest-api/#customconfigurationvalue-1) | false | none | This is a configuration value for which the backed does have no information. This is likely a custom configuration key that a user manually entered or a configuration value that is a result from a downgrade and is only present in newer Access Server versions. |
| »»»» value | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| derived\_from | default |
| derived\_from | local\_db |
| derived\_from | cluster\_db |
| derived\_from | mysql\_standalone\_db |
| derived\_from | as\_conf |
| derived\_from | environment |
| derived\_from | runtime |
| derived\_from | other |
| type | custom |
| type | integer |
| type | boolean |
| type | string |
| category | deprecated |
| category | removed |
| category | normal |
| category | required |
| category | derived |
| category | advanced |
| category | custom |
| type\_hint | ipv4Address |
| type\_hint | ipv6Address |
| type\_hint | ipAddress |
| type\_hint | hostname |
| type\_hint | pemCertificate |
| type\_hint | pemPrivateKey |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"names": [
"vpn.server.cipher"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-items/{configurationProfile}/list',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"total": 0,
"items": [
{
"name": "vpn.server.cipher",
"derived_from": "default",
"type": "custom",
"description": "string",
"category": "deprecated",
"value": 0,
"default_value": 0,
"max_value": 0,
"min_value": 0
}
]
}
```
#### post\_**config-items**{configurationProfile}
`POST /config-items/{configurationProfile}`
Update/set configuration items. This is implemented as an atomic operation. All configuration items are checked and only if all can be set, this method will succeed. Otherwise no configuration item is updated/set. If an item is set to null it is deleted from the configuration and will use the default instead.
##### Body parameter
```json
{
"property1": "string",
"property2": "string"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Configuration items were successfully updated/set | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Configuration value do not have the correct type or another problems occurred. See errorReason for detailed information | [errorReasonDetail](https://openvpn.net/as-docs/rest-api/#errorreasondetail-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | configuration profile to be changed was not found | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"property1": "string",
"property2": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/config-items/{configurationProfile}',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "config values had errors",
"detail": {
"host.name": "Contains invalid character %",
"server.port": "Must be an integer between 1 and 65335"
}
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| configurationProfile | path | [configurationProfile](https://openvpn.net/as-docs/rest-api/#configurationprofile-3) | true | none |
| body | body | object | true | none |
| » **additionalProperties** | body | string | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
### saml
API endpoints that are related to SAML based authentication
#### post\_\_saml\_acs
`POST /saml/acs`
This endpoint is different from others from that perspective, it is available under /saml/acs of an AS server instead of /webapi/v1/… . This endpoint is called as part of the SAML authentication process, precisely, when saml assertion was obtained on successful login to IdP Provider. IdP Provider sends assertion request to /saml/acs AS url, so that AS may finish login process.
##### Body parameter
```yaml
RelayState: string
SAMLResponse: string
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | This will return a html page similar to index.html that loads the web site of the application. In the source code it will embed a javascript fragment that contains the assertion as javascript variable SAMLResponse itself and the RelayState as RelayState variable. | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Throw validation error if wrong request passed | None |
| 405 | [Method Not Allowed](https://tools.ietf.org/html/rfc7231#section-6.5.5) | Only POST for this url is allowed. Throw unsupported error if method is not POST | None |
```javascript
const inputBody = '{
"RelayState": "string",
"SAMLResponse": "string"
}';
const headers = {
'Content-Type':'application/x-www-form-urlencoded',
'Accept':'text/html'
};
fetch('/api/saml/acs',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
| » RelayState | body | string | false | cws, profile or vpnauthnodeidsessionid |
| » SAMLResponse | body | string(xml string encoded in base64 format) | true | none |
###### This will return a html page similar to index.html that loads the web site of the application. In the source code it will embed a javascript fragment that contains the assertion as javascript variable SAMLResponse itself and the RelayState as RelayState variable.
```
"< SAMLResponse = \"[samlassertion data]\"; RelayState = \"cwslogin\"; [content of index.html]"
```
###### Throw validation error if wrong request passed
```
"< HEAD content SAML authentication failed
assertion request is invalid
"
```
###### Only POST for this url is allowed. Throw unsupported error if method is not POST
```
"< HEAD content SAML authentication failed
assertion method is not supported
"
```
##### Response Schema
This operation does not require authentication
#### get\_\_saml\_metadata
`GET /saml/metadata`
This endpoint is different from others from that perspective, it is available under /saml/metadata of AS server instead of /webapi/v1/… . This endpoint may be called as part of the SAML authentication process, when IDP may request Service Provider metadata.
##### SAML is not configured or invalid configuration
```
"< HEAD content 404 Not Found
SAML not configured or invalid configuration
"
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | This will return xml file with metadata of the Service Provider | string |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | SAML is not configured or invalid configuration | None |
```javascript
const headers = {
'Accept':'application/samlmetadata+xml',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/saml/metadata',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
##### Response Schema
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### get\_\_saml\_redirect
`GET /saml/redirect`
This endpoint is used by vpn session authentication process to redirect to the SAML IdP if the URL exceeds the length that is directly transmittable via the VPN protocol.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 302 | [Found](https://tools.ietf.org/html/rfc7231#section-6.4.3) | Responds with redirect to Identity Provider url | None |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | Errors can be: Wrong RelayState parameter or assertion request is invalid | None |
This operation does not require authentication
```javascript
fetch('/api/saml/redirect',
{
method: 'GET'
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
#### get\_\_auth\_get-idp-url
`GET /auth/get-idp-url`
This endpoint gives the URL of external Identity Provider for the user to redirect to and start the SAML authentication process.
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Identity Provider URL to redirect to | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Errors can be: Wrong RelayState parameter or SAML configuration error | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
This operation does not require authentication
```javascript
const headers = {
'Accept':'string'
};
fetch('/api/auth/get-idp-url',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| relay\_state | query | string | false | If not set, the cws relay\_state is assumed |
### vpn
directly related to the connected VPN users
#### vpnAuthSAMLAssertion
`POST /auth/vpn/vpnsaml`
forwards a SAML assertion to the VPN authentication mechanism. The user UI in this case just forwards the assertion. Typically these are SAML assertions with a relay state starting with vpnauth. The UI should show show a successful forward.
##### Body parameter
```json
{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | object | false | none |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Assertion Success | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid SAML assertion in the case if empty string was passed as saml assertion | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 401 | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | Wrong Relay State or other assertion error | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"assertion": "string",
"relay_state": "vpnauth~nod1~Dfk3287761d"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/auth/vpn/vpnsaml',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
#### get\_\_vpn\_status
`GET /vpn/status`
gets the currently connected client and general status of the OpenVPN daemon. Note that this API currently does not feature pagination as the backend always gets all information anyway and pagination would require the backend to drop most of the information to avoid a little bit of data transfer.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Vpn Server status | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"vpn_clients": [
{
"daemon_id": "openvpn_7",
"client_id": 7,
"bytes_sent": 0,
"bytes_received": 0,
"commonname": "plato_AUTOLOGIN",
"username": "plato",
"connected_since": "2019-08-24T14:15:22Z",
"datachannel_cipher": "ChaCha20-Poly1305",
"real_address": "1.2.7.8:23123",
"virtual_ipv4_address": "10.0.0.7",
"virtual_ipv6_address": "fd00:f00f::b00f"
}
],
"vpn_daemons": {
"property1": {
"dco": true,
"version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
},
"property2": {
"dco": true,
"version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
}
}
}
```
##### Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » vpn\_clients | \[allOf\] | false | none | List of connected VPN clients |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [vpnConnectionID](https://openvpn.net/as-docs/rest-api/#vpnconnectionid-1) | false | none | none |
| »»» daemon\_id | [daemonID](https://openvpn.net/as-docs/rest-api/#daemonid-1) | true | none | an ID that identifies the OpenVPN daemon that the client is connected to |
| »»» client\_id | [clientID](https://openvpn.net/as-docs/rest-api/#clientid-1) | true | none | the client ID of the connected client. This ID is only unique for a specific daemonId. Or with other words, only daemonID and clientID together uniquely identify a client. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» bytes\_sent | integer | false | none | number of bytes sent |
| »»» bytes\_received | integer | false | none | number of bytes received |
| »»» commonname | string | false | none | the common name the client uses in its certificate. |
| »»» username | string | false | none | username of the client |
| »»» connected\_since | string(date-time) | false | none | time in UTC since when the client is connected. |
| »»» datachannel\_cipher | string | false | none | the data channel cipher that is used with this client. |
| »»» real\_address | string | false | none | the IP address the client is connected from |
| »»» virtual\_ipv4\_address | string | false | none | the virtual or VPN address of the client |
| »»» virtual\_ipv6\_address | string | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » vpn\_daemons | object | false | none | none |
| »» **additionalProperties** | [vpnDaemonStatus](https://openvpn.net/as-docs/rest-api/#vpndaemonstatus-1) | false | none | status of a VPN daemon |
| »»» dco | boolean | false | none | if DCO is used on this daemon instance |
| »»» version | string | false | none | the OpenVPN 2.x version of the daemon |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
#### disconnectClient
`POST /vpn/client/disconnect`
disconnects a client from the VPN server, either user or clients fields is mandatory.
##### Body parameter
```json
{
"reason": "John should not be working after hours",
"client_reason": "Client disconnected for administrative reasons",
"users": [
"niccolo@paganini.it"
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | any | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | client has been successfully disconnected | None |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | One or more of the clients failed to disconnect | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | A client with the specified daemon and client id could not be found. | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"reason": "John should not be working after hours",
"client_reason": "Client disconnected for administrative reasons",
"users": [
"niccolo@paganini.it"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/vpn/client/disconnect',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"reason": "Your password must not include parts of Cthulhu's chant.",
"title": "Password validation failed"
}
```
### cws
cws stands for client website. These APIs are the ones that can be used as normal users and do not require admin permission for basic operations. Some have extended functionality that require admin privileges like acting on the behalf of another user.
#### generateInstallerUrl
`POST /installer-url`
##### Body parameter
```json
{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [installerProfileRequest](https://openvpn.net/as-docs/rest-api/#installerprofilerequest-1) | false | none |
| » user | body | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| » installer\_type | body | [installerType](https://openvpn.net/as-docs/rest-api/#installertype-1) | true | Type of the installer binary that should be created for installation. |
| » profile\_type | body | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | false | none |
| » tls\_crypt\_v2 | body | boolean | false | The client is capable of TLS-Crypt v2 |
###### Enumerated Values
| Parameter | Value |
| --- | --- |
| » installer\_type | win\_v3 |
| » installer\_type | mac\_v3 |
| » installer\_type | win |
| » installer\_type | mac |
| » installer\_type | ios |
| » installer\_type | android |
| » installer\_type | linux |
| » profile\_type | autologin |
| » profile\_type | userlogin |
| » profile\_type | generic |
| » profile\_type | epki-generic |
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Installer URL was successfully generated | string |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | “Generation of installer url was not permitted” or “Requested installer is not downloadable” or “An error occurred while trying to download OpenVPN Connect from the server. The required client installer file was not found on the server” | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const inputBody = '{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/installer-url',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
### userprop
APIs that related to retrieving and modifying user properties.
#### getdefaultuserprops
`GET /users/defaultuser`
Retrieves the special meta data user, usually called **DEFAULT** that defines the defaults for users with “type”: “user\_default”.
##### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | [userPropUserDefault](https://openvpn.net/as-docs/rest-api/#userpropuserdefault-1) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
To perform this operation, you must be authenticated by means of one of the following methods: AuthToken
```javascript
const headers = {
'Accept':'application/json',
'X-OpenVPN-As-AuthToken':'API_KEY'
};
fetch('/api/users/defaultuser',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
```
```json
{
"name": "string",
"deny": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"deny_web": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"admin": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"autologin": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"auth_method": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cc_commands": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"totp": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"password_strength": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"allow_password_change": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"reroute_gw": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"allow_generate_profiles": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"bypass_subnets": [
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false
}
],
"def_deny": true,
"cli_script_connect_win_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"property2": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
}
},
"group": "stringsection"
}
```
#### getuserprops
`POST /users/list`
provides a list of all profiles of the user. This does NOT include the default user with “type”: “user\_default”. To fetch the default user use the /users/defaultuser
##### Body parameter
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "admin",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"group": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"users": [
"niccolo@paganini.it"
],
"proplist": [
"string"
]
}
```
##### Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| body | body | [userRequestParameters](https://openvpn.net/as-docs/rest-api/#userrequestparameters-1) | false | none |
###### standard response when there insufficient rights to use an API.
```json
{
"message": "Insufficient privileges to use this API"
}
```
##### Responses
| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Success | Inline |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | only admin users are allowed to use this API | [errorReason](https://openvpn.net/as-docs/rest-api/#errorreason) |
##### Response Schema
Status Code **200**
**A list of all or subset of profiles**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » total | integer | false | none | total number of users that match if pagination is not in effect, this matches the size of the provided array |
| » profiles | \[allOf\] | false | none | none |
**allOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userProp](https://openvpn.net/as-docs/rest-api/#userprop-3) | false | none | This hold the attributes of the userprop that is not specifically handled in a special way like passwords or group members. OpenAPI does not allow to specify description along with $ref so the description for the individual keys is in this descriptions. - deny (boolean): If true cannot connect or login (prop\_deny) - deny\_web (boolean): If true cannot login to web (prop\_deny\_web) - compile (boolean): If true the type is ‘user\_compile’ instead of ‘user\_connect’. (user record also queried on nftables/iptables compile and not only on connect) - admin (boolean): user is admin (prop\_superuser) - autologin (boolean): autologin profile generation is allowed by the user themselves (prop\_autologin) - auth\_method (string): the authentication method that will be used for the user. Maps to user\_auth\_type and default configuration etc. - cc\_commands: custom OpenVPN directives that will imported for the user on the server side (prop\_cc\_cmds) - totp: specifies whether TOTP based MFA is required (prop\_google\_auth) - password\_strength: password strength check is enforced when changing the password for local auth (prop\_pwd\_strength/cs.cws.pwd\_strength) - allow\_password\_change (boolean): specifies if a user is allowed to change the password themselves when local auth is used (prop\_pwd\_change). If not set on users the global default server key cs.cws.pwd\_change is used as default. Admins can always change user passwords (including their own). - reroute\_gw (string): one of ‘disable’, ‘dns\_only’, ‘global’ Disables redirection of the default route and/or DNS on the client. This does not block it on the backend, if blocking on the backend is required, access lists should be added in addition. Defaults to ‘global’ if not set. The setting global will follow the configuration key ‘vpn.client.routing.reroute\_gw’.(prop\_reroute\_gw\_override) - allow\_generate\_profiles (prop\_autogenerate): allow users themselves to generate connection profiles |
| »»» name | string | false | none | the name of the user or group. |
| »»» deny | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»»» value | any | true | none | the value that this property has. If inherited is false, this is identical to inheritedValue |
**oneOf**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | string | false | none | none |
**xor**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»»» **anonymous** | boolean | false | none | none |
**continued**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »»»» inherited | boolean | false | none | specifies if this value is inherited from an upper level if this |
| »»»» inherited\_source\_type | string | false | none | describes where the inherited values comes. This can be from the default user properties (**default**) or from a global configuration settings or from a group If the property is explicitly set (ie inherited is false), this property indicates what the property would inherit from if inherit is false. |
| »»»» inherited\_source\_name | string | false | none | for the inherited types where knowing the name of the source can be beneficial. Like the group name or in some cases the configuration key. If the property is explicitly set (ie inherited is false), this property indicates what the property would inherit from if inherit is false. |
| »»» deny\_web | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» admin | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» autologin | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» auth\_method | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» cc\_commands | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» totp | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» password\_strength | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» allow\_password\_change | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» reroute\_gw | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» allow\_generate\_profiles | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| »»» bypass\_subnets | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet-1)\] | false | none | Subnets or hosts (represented subnet with a /32 or /128 netmask) that are installed as bypass routes on the client, i.e. that will bypass the VPN and use the normal non-VPN connection. |
| »»»» ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| »»»» netip | string | false | none | the network IP address. |
| »»»» prefix\_length | integer | false | none | length of the prefix in CIDR notation |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userLevelOnlyProps](https://openvpn.net/as-docs/rest-api/#userlevelonlyprops-1) | false | none | this describes the properties that are only allowed on the user level itself are not inheritable from other levels |
| »»» password\_defined | boolean | false | none | This indicates whether the user has a password set. The API will NOT provide the hash of the password but only the information if a user password has been set. |
| »»» mfa\_status | string | false | none | the status of the multi factor authentication. This is a read-only property that combines totp and totp\_locked into a single status. |
| »»» totp\_locked | boolean | false | none | specifies if the TOTP for the user is locked/enrolled. If true, secret is no longer viewable |
| »»» group | string | false | none | the group a user belongs too (conn\_group) |
| »»» static\_ipv4 | string | false | none | optional property. Maps to conn\_ip |
| »»» static\_ipv6 | string | false | none | optional property. Maps to conn\_ip6 |
| »»» dmz\_ip | \[[DMZIP](https://openvpn.net/as-docs/rest-api/#dmzip-1)\] | false | none | The IP addresses and port-ranges that are exposed on this client. |
| »»»» ip | string | true | none | the external IP address of the Access Server |
| »»»» protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol-1) | false | none | specifies a Layer 4 protocol (e.g. udp or tcp) |
| »»»» start\_port | integer | false | none | the starting port for the dmz. If not specified all ports will be forwarded |
| »»»» end\_port | integer | false | none | the end port of the ports that are being forwarded. If not specified only a single port (the start\_port) is forwarded. |
| »»» dmz\_ipv6 | \[[DMZIP](https://openvpn.net/as-docs/rest-api/#dmzip-1)\] | false | none | The IPv6 addresses and port-ranges that are exposed on this client. |
| »»» compile | boolean | false | none | If true the type is ‘user\_compile’ instead of ‘user\_connect’. |
| »»» totp\_secret | string | false | none | the TOTP secret code according to RFC 6238. Note, that this is value might not be present for locked users in later versions (pvt\_google\_auth\_secret). |
| »»» totp\_admin\_only | boolean | false | none | totp\_admin\_only only AS admins can generate and view Google Authenticator secrets (prop\_google\_auth\_admin\_locked) |
| »»» client\_to\_server\_subnets | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet-1)\] | false | none | \< Subnets that are behind the client. I.e. the client will be a router/gateway for the subnets specified in this array. On the server side, this is split into ipv4 and ipv6 subnets (c2s\_subnets and c2s\_subnets6) but this API represents that as a single list. Use the ipv6 flag of the subnet to determine the address family. |
**and**
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [userPropScripts](https://openvpn.net/as-docs/rest-api/#userpropscripts-1) | false | none | This hold the attributes of the userprop that control client side scripting. It is not handled in a special way like passwords or group members. OpenAPI does not allow to specify description along with $ref so the description for the individual keys is in this descriptions. - Client side scripting: prop\_cli.script.\.\.\
- Client script env: prop\_cli.script\_env.win\|prop\_cli.script\_env.mac”
example environment variable: “prop\_cli.script\_env.win.MSI\_URL”: “https://secure.openvpn.net/tmp/bogi.msi”,
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| cli\_script\_connect\_win\_user\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_win\_user\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_win\_admin\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_win\_admin\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_mac\_user\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_mac\_user\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_mac\_admin\_connect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_mac\_admin\_disconnect | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_win\_env | object | false | none | environment variables for the Windows script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
| cli\_script\_connect\_mac\_env | object | false | none | environment variables for the macOS script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | [userPropValue](https://openvpn.net/as-docs/rest-api/#userpropvalue-1) | false | none | This object describes a single user property value. If it is |
```json
{
"cli_script_connect_win_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_user_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_connect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_mac_admin_disconnect": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
},
"property2": {
"value": "string",
"inherited": true,
"inherited_source_type": "default",
"inherited_source_name": "administrators"
}
}
}
```
#### userPropScriptsSet
The same as userPropScripts schema. With the diffirence that it is used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| cli\_script\_connect\_win\_user\_connect | string | false | none | none |
| cli\_script\_connect\_win\_user\_disconnect | string | false | none | none |
| cli\_script\_connect\_win\_admin\_connect | string | false | none | none |
| cli\_script\_connect\_win\_admin\_disconnect | string | false | none | none |
| cli\_script\_connect\_mac\_user\_connect | string | false | none | none |
| cli\_script\_connect\_mac\_user\_disconnect | string | false | none | none |
| cli\_script\_connect\_mac\_admin\_connect | string | false | none | none |
| cli\_script\_connect\_mac\_admin\_disconnect | string | false | none | none |
| cli\_script\_connect\_win\_env | object | false | none | environment variables for the Windows script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | string | false | none | none |
| cli\_script\_connect\_mac\_env | object | false | none | environment variables for the macOS script to run, each key will specify the name of the environment variable. |
| » **additionalProperties** | string | false | none | none |
```json
{
"cli_script_connect_win_user_connect": "string",
"cli_script_connect_win_user_disconnect": "string",
"cli_script_connect_win_admin_connect": "string",
"cli_script_connect_win_admin_disconnect": "string",
"cli_script_connect_mac_user_connect": "string",
"cli_script_connect_mac_user_disconnect": "string",
"cli_script_connect_mac_admin_connect": "string",
"cli_script_connect_mac_admin_disconnect": "string",
"cli_script_connect_win_env": {
"MSI_URL": "https://secure.openvpn.net/tmp/bogi.msi",
"lucky_number": "23",
"SCRIPT_VER": "alpha9"
},
"cli_script_connect_mac_env": {
"property1": "string",
"property2": "string"
}
}
```
#### serviceStatusEnum
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | on |
| **anonymous** | disabled |
| **anonymous** | error |
| **anonymous** | enabled |
```json
"on"
```
#### serviceWarning
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| tag | string | false | none | A tag assigned to the type of warning/error message |
| message | string | false | none | A short summary of the warning in question |
| description | any | false | none | A longer more detailed description of the warning |
| severity | string | false | none | The level of the warning. The level error signals a hard error that prevents Access Server from starting and ok signal |
###### Enumerated Values
| Property | Value |
| --- | --- |
| severity | ok |
| severity | info |
| severity | warning |
| severity | critical |
| severity | error |
```json
{
"tag": "DCO_NOT_ACTIVE",
"message": "Insecure VPN cipher in use",
"description": "Insecure cipher DES-EDE3-CBC allowed for VPN encryption. Consider removing this cipher from vpn.server.data_ciphers (AES-256-GCM:DES-EDE3-CBC) and/or disabling vpn.server.enable_cipher_fallback (False)",
"severity": "ok"
}
```
#### serviceStatus
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| status | [serviceStatusEnum](https://openvpn.net/as-docs/rest-api/#servicestatusenum) | false | none | none |
| error | \[[serviceWarning](https://openvpn.net/as-docs/rest-api/#servicewarning)\] | false | none | a list of important error message/warnings that impact current operation |
```json
{
"status": "on",
"error": [
{
"tag": "DCO_NOT_ACTIVE",
"message": "Insecure VPN cipher in use",
"description": "Insecure cipher DES-EDE3-CBC allowed for VPN encryption. Consider removing this cipher from vpn.server.data_ciphers (AES-256-GCM:DES-EDE3-CBC) and/or disabling vpn.server.enable_cipher_fallback (False)",
"severity": "ok"
}
]
}
```
#### serverStatus
retrieve the status of the internal services of the server.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| last\_restarted | string(date-time) | false | none | the last time the server was restarted |
| service\_status | object | false | none | an object containing the status of the various internal services. The key name holds the name of the service. |
| » **additionalProperties** | [serviceStatus](https://openvpn.net/as-docs/rest-api/#servicestatus) | false | none | none |
| auth\_module\_status | object | false | none | an object containing the status of the various authentication services. The key name holds the name of the service. |
| » **additionalProperties** | [serviceStatusEnum](https://openvpn.net/as-docs/rest-api/#servicestatusenum) | false | none | none |
```json
{
"last_restarted": "2019-08-24T14:15:22Z",
"service_status": {
"property1": {
"status": "on",
"error": []
},
"property2": {
"status": "on",
"error": []
}
},
"auth_module_status": {
"property1": "on",
"property2": "on"
}
}
```
#### serverInterface
describes a Linux network interface and the associated primary networks
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| name | any | false | none | the name identifying the interface |
| networks | \[[IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet-1)\] | false | none | IP addresses assigned to the interface |
```json
{
"name": "eth0",
"networks": [
{
"netip": "fd00::18cc:1b01:a772:50e1",
"ipv6": true,
"prefix_len": "64"
},
{
"netip": "10.0.0.1",
"ipv6": false,
"prefix_len": 25
},
{
"netip": "192.168.0.1",
"ipv6": false,
"prefix_len": 24
}
]
}
```
#### serverConfig
Describes global settings for AS server available to any authenticated users..
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| control\_channel\_security | [controlChannelSecurity](https://openvpn.net/as-docs/rest-api/#controlchannelsecurity) | true | none | none |
| installers | \[[installerType](https://openvpn.net/as-docs/rest-api/#installertype-1)\] | true | none | \[Type of the installer binary that should be created for installation.\] |
| hide\_profiles\_page | boolean | false | none | If True, the Connections profile page is hidden |
| password\_min\_len | integer | true | none | Minimal length for the password if strength check is enabled. |
| disable\_open\_in\_app | boolean | true | none | If True then disable in app on UI |
| admin\_port | integer | true | none | port for Admin site |
| shared\_origin | boolean | true | none | CWS and Admin ui are both available on same origin (protocol + hostname + port) as this API endpoint being called. |
```json
{
"control_channel_security": "none",
"installers": [
"win_v3"
],
"hide_profiles_page": true,
"password_min_len": 0,
"disable_open_in_app": true,
"admin_port": 0,
"shared_origin": true
}
```
#### controlChannelSecurity
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | none |
| **anonymous** | tls-auth |
| **anonymous** | tls-crypt |
| **anonymous** | tls-crypt-v2 |
```json
"none"
```
#### serverInfo
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| version | string | false | none | the version number of Access Server |
| build | string | false | none | the build of Access Server. |
| web\_version | string | false | none | the build version number of Access Server UI |
| web\_override | boolean | false | none | if true the version of the web ui that is used comes from an override-web.zip instead of the bundled version |
| client\_version | string | false | none | version of the embedded client package |
| os\_distribution | string | false | none | a human readable identifier of the current (Linux) distribution like PRETTY\_NAME from /etc/os-release |
| architecture | string | false | none | the CPU architecture |
| cores | integer | false | none | the number of cores visible to the operating system |
| os\_hostname | string | false | none | Operating system’s hostname |
###### Enumerated Values
| Property | Value |
| --- | --- |
| architecture | arm64 |
| architecture | amd64 |
```json
{
"version": "2.13.0-internal",
"build": "18eba991",
"web_version": "2.12.7-82fda2",
"web_override": true,
"client_version": [
"27"
],
"os_distribution": "Ubuntu 24.04.6 LTS",
"architecture": "arm64",
"cores": 0,
"os_hostname": "access-server-os-hostname"
}
```
#### eulaStatus
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| eula\_version\_as | integer | false | none | The version of the AS EULA |
| eula\_web\_hash | string(sha256) | false | none | A SHA256 string in hex format without : separators |
| eula\_accepted | boolean | false | none | indicates whether the config setting (aui.eula\_version) has the same value as eula\_version\_as |
```json
{
"eula_version_as": 7,
"eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
"eula_accepted": true
}
```
#### notificationMessage
notification msg stored in notificationdb
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| notification\_type | string | true | none | the type of notification |
###### Enumerated Values
| Property | Value |
| --- | --- |
| notification\_type | CLUSTER\_RESTART\_PENDING |
| notification\_type | NODE\_RESTARTED |
```json
{
"notification_type": "CLUSTER_RESTART_PENDING"
}
```
#### clusterProps
properties common to all nodes in the cluster.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| rr\_dns\_hostname | string | false | none | the Round-Robin hostname that uniquely identifies the cluster |
| rr\_dns\_new\_nodes | boolean | false | none | if true, use rr\_dns\_hostname as node hostname for new nodes joining the cluster |
```json
{
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true
}
```
#### clusterNode
describes a node in the cluster. The certificate field is the certificate that the node will present on its api\_endpoint and that is expected to be used to verify the identity of the node.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| name | string | true | none | the name that uniquely identifies the cluster node \[node\_name\] |
| api\_endpoint | [apiEndpoint](https://openvpn.net/as-docs/rest-api/#apiendpoint-1) | false | none | the API endpoint to specifically address a node. Requires format https:ip/hostname:port. Note that https is necessary because certificateFingerprint is used by https client to verify it is indeed talking to the right node. |
| certificate\_fingerprint | [certificateFingerprint](https://openvpn.net/as-docs/rest-api/#certificatefingerprint-1) | false | none | The SHA256 hash of the certificate body, also known as the fingerprint of the certificate. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C"
}
```
#### clusterNodeJoinRequest
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterNode](https://openvpn.net/as-docs/rest-api/#clusternode-1) | false | none | describes a node in the cluster. The certificate field is the certificate that the node will present on its api\_endpoint and that is expected to be used to verify the identity of the node. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » mysqluri | [mysqluri](https://openvpn.net/as-docs/rest-api/#mysqluri) | false | none | the URI of the mysql server. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/"
}
```
#### clusterNodeCreateRequest
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterNodeJoinRequest](https://openvpn.net/as-docs/rest-api/#clusternodejoinrequest-1) | false | none | none |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [clusterProps](https://openvpn.net/as-docs/rest-api/#clusterprops-1) | false | none | properties common to all nodes in the cluster. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » rr\_update\_node | boolean | false | none | if true: update host.name in confdb\_local to rr\_dns\_hostname in clusterdb when creating the cluster. if false: do not use rr\_dns\_hostname to update host.name in confdb\_local, at cluster creation time. This is to provide admin the flexibility to update host.name to rr\_dns\_hostname at a later stage than cluster creation. |
```json
{
"name": "vienna.example.com",
"api_endpoint": "https://node1:945",
"certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
"mysqluri": "mysql://user:password@mysql.example.com:3306/",
"rr_dns_hostname": "cluster.example.com",
"rr_dns_new_nodes": true,
"rr_update_node": true
}
```
#### mysqluri
the URI of the mysql server.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | the URI of the mysql server. |
```json
"mysql://user:password@mysql.example.com:3306/"
```
#### profileRequest
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| user | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | none | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | true | none | none |
| tls\_crypt\_v2 | boolean | false | none | The client is capable of TLS-Crypt v2 |
| comment | string | false | none | A user-defined comment |
| ignore\_missing\_user | any | false | none | if this is flag, which requires admin rights, is set, a profile will be created even if the specified user does not exist. |
```json
{
"user": "niccolo@paganini.it",
"profile_type": "autologin",
"tls_crypt_v2": true,
"comment": "connected from my iPhone",
"ignore_missing_user": null
}
```
#### installerProfileRequest
Fields for request to get installer download url
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| user | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | none | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| installer\_type | [installerType](https://openvpn.net/as-docs/rest-api/#installertype-1) | true | none | Type of the installer binary that should be created for installation. |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | false | none | none |
| tls\_crypt\_v2 | boolean | false | none | The client is capable of TLS-Crypt v2 |
```json
{
"user": "niccolo@paganini.it",
"installer_type": "win_v3",
"profile_type": "autologin",
"tls_crypt_v2": true
}
```
#### commonPaginationParameters
the common parameters that all APIs that support pagination have. order\_by and sort\_by keys are dependent on the object that is paginated
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| page\_size | integer | false | none | number of the profiles that are returned |
| offset | integer | false | none | offset for pagination |
| sort\_by | [sortingDirection](https://openvpn.net/as-docs/rest-api/#sortingdirection-1) | false | none | The direction of sorting |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc"
}
```
#### profileRequestParameters
This specifies the filters and parameters for the request of the user profiles.
Note, that some of the search fields do not have indices on the backend database and might be slow.
Using the user filter with anything than the own username will cause an error for non-admin users.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters-1) | false | none | the common parameters that all APIs that support pagination have. order\_by and sort\_by keys are dependent on the object that is paginated |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [certProfileSorting](https://openvpn.net/as-docs/rest-api/#certprofilesorting-1) | false | none | specifies by which attribute profiles should be sorted |
| » filters | object | false | none | none |
| »» user | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» serial\_number | [filterInteger](https://openvpn.net/as-docs/rest-api/#filterinteger-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» tls\_crypt\_v2 | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool-1) | false | none | This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal. |
| »» last\_used | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» not\_before | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» not\_after | [filterTime](https://openvpn.net/as-docs/rest-api/#filtertime) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). |
| »» comment | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» signing\_ca\_cn | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere-1) | false | none | This takes a number of field that should be searched for the string specified by value. The search is always a substring match and will match if ANY of the fields have a substring that matches. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "serial",
"filters": {
"user": {
"operation": "substring",
"value": "vio"
},
"serial_number": {
"value": 400,
"operation": "less_than"
},
"tls_crypt_v2": {
"value": true
},
"last_used": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_before": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"not_after": {
"start": "2019-08-24",
"end": "2019-08-24"
},
"comment": {
"operation": "substring",
"value": "vio"
},
"signing_ca_cn": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
#### userRequestParameters
This indicates the filters that can be used for a requesting user parameters. If more than one filter is specified, the items returned must match all of the filters. The anywhere filter is special and can be only used alone.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters-1) | false | none | the common parameters that all APIs that support pagination have. order\_by and sort\_by keys are dependent on the object that is paginated |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [userSorting](https://openvpn.net/as-docs/rest-api/#usersorting-1) | false | none | specifies by which attribute profiles should be sorted |
| » filters | any | false | none | none |
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »»» group | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [commonUserGroupFilters](https://openvpn.net/as-docs/rest-api/#commonusergroupfilters-1) | false | none | filters that can be applied to both user and group requests |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » users | \[[username](https://openvpn.net/as-docs/rest-api/#username-1)\] | false | none | a list of usernames that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that usernames that are not found in the backend will be missing from the response. |
| » proplist | [userPropList](https://openvpn.net/as-docs/rest-api/#userproplist-1) | false | none | A list of user properties to request. If this is null then all user properties for the user/group will be returned. Otherwise the list of user properties that should be returned. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "admin",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"group": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"users": [
"niccolo@paganini.it"
],
"proplist": [
"string"
]
}
```
#### commonUserGroupFilters
filters that can be applied to both user and group requests
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| admin | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool-1) | false | none | This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal. |
| autologin | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool-1) | false | none | This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal. |
| anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere-1) | false | none | This takes a number of field that should be searched for the string specified by value. The search is always a substring match and will match if ANY of the fields have a substring that matches. |
```json
{
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": [
"username",
"group"
]
}
}
```
#### tokenRequestParameters
parameters to be used when creating a new token-url. For non-admin usage only the profile type should be specified as setting most other parameters to values higher than default will cause errors.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| lifetime | integer | false | none | Optional lifetime in seconds that the token should be valid for. Longer lifetimes than default require admin privileges. |
| usages | integer | false | none | Optional number of usages that this token can be used to generate a profile. Defaults to a single use if not provided. Specifying more than more usage requires admin privileges. |
| profile\_type | [profileType](https://openvpn.net/as-docs/rest-api/#profiletype-1) | true | none | none |
| username | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | none | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
```json
{
"lifetime": 0,
"usages": 0,
"profile_type": "autologin",
"username": "niccolo@paganini.it"
}
```
#### logDBRequestParameters
This specifies the filters and parameters for the request of the log database requests. Note, that this currently only includes the fields that were considered necessary of logDBRecord and that some search might not have indices in the database and might be slow.
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters-1) | false | none | the common parameters that all APIs that support pagination have. order\_by and sort\_by keys are dependent on the object that is paginated |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [logDBSortingFields](https://openvpn.net/as-docs/rest-api/#logdbsortingfields-1) | false | none | Enum representing valid sorting fields for LogDB. |
| » filters | object | false | none | none |
| »» start\_time | [filterTimeOrDuration](https://openvpn.net/as-docs/rest-api/#filtertimeorduration-1) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). Same with relative time for start and end. |
| »» timestamp | [filterTimeOrDuration](https://openvpn.net/as-docs/rest-api/#filtertimeorduration-1) | false | none | This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). Same with relative time for start and end. |
| »» duration | [filterDuration](https://openvpn.net/as-docs/rest-api/#filterduration-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» node | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» username | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» active | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool-1) | false | none | This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal. |
| »» error | [filterBool](https://openvpn.net/as-docs/rest-api/#filterbool-1) | false | none | This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal. |
| »» service | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» virtual\_ipv4\_address | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» bytes\_sent | [filterBandwidth](https://openvpn.net/as-docs/rest-api/#filterbandwidth) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» bytes\_received | [filterBandwidth](https://openvpn.net/as-docs/rest-api/#filterbandwidth) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» gui\_version | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» version | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» platform | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| »» anywhere | [filterAnywhere](https://openvpn.net/as-docs/rest-api/#filteranywhere-1) | false | none | This takes a number of field that should be searched for the string specified by value. The search is always a substring match and will match if ANY of the fields have a substring that matches. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "node",
"filters": {
"start_time": {
"start_relative": "20d",
"end_relative": "15d 20m"
},
"timestamp": {
"start_relative": "20d",
"end_relative": "15d 20m"
},
"duration": {
"value": "20d",
"operation": "less_than"
},
"node": {
"operation": "substring",
"value": "vio"
},
"username": {
"operation": "substring",
"value": "vio"
},
"active": {
"value": true
},
"error": {
"value": true
},
"service": {
"operation": "substring",
"value": "vio"
},
"virtual_ipv4_address": {
"operation": "substring",
"value": "vio"
},
"bytes_sent": {
"value": "20kb",
"operation": "less_than"
},
"bytes_received": {
"value": "20kb",
"operation": "less_than"
},
"gui_version": {
"operation": "substring",
"value": "vio"
},
"version": {
"operation": "substring",
"value": "vio"
},
"platform": {
"operation": "substring",
"value": "vio"
},
"anywhere": {
"value": "bass",
"fields": []
}
}
}
```
#### filterTimeOrDuration
This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞). Same with relative time for start and end.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| start | string(date-time) | false | none | none |
| end | string(date-time) | false | none | none |
| start\_relative | string | false | none | none |
| end\_relative | string | false | none | none |
```json
{
"start_relative": "20d",
"end_relative": "15d 20m"
}
```
#### filterBandwidth
This specifies that the result should be filtered by this attribute with the specified operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | any | true | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | string | false | none | none |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | integer | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | less\_than |
| operation | greater\_than |
```json
{
"value": "20kb",
"operation": "less_than"
}
```
#### filterString
This specifies that the result should be filtered by this attribute with the specified operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | substring |
| operation | not\_equal |
```json
{
"operation": "substring",
"value": "vio"
}
```
#### filterDuration
This specifies that the result should be filtered by this attribute with the specified operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | less\_than |
| operation | greater\_than |
```json
{
"value": "20d",
"operation": "less_than"
}
```
#### filterInteger
This specifies that the result should be filtered by this attribute with the specified operation.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | integer | true | none | none |
| operation | string | true | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| operation | equal |
| operation | less\_than |
| operation | greater\_than |
| operation | not\_equal |
```json
{
"value": 400,
"operation": "less_than"
}
```
#### filterTime
This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of \[2020-02-02, ∞).
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| start | string(date) | false | none | none |
| end | string(date) | false | none | none |
```json
{
"start": "2019-08-24",
"end": "2019-08-24"
}
```
#### filterBool
This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | boolean | true | none | none |
```json
{
"value": true
}
```
#### filterAnywhere
This takes a number of field that should be searched for the string specified by value. The search is always a substring match and will match if ANY of the fields have a substring that matches.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| value | string | false | none | the substring to search in all specified fields |
| fields | \[string\] | false | none | names of the fields to be searched |
```json
{
"value": "bass",
"fields": [
"username",
"group"
]
}
```
#### groupRequestParameters
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [commonPaginationParameters](https://openvpn.net/as-docs/rest-api/#commonpaginationparameters-1) | false | none | the common parameters that all APIs that support pagination have. order\_by and sort\_by keys are dependent on the object that is paginated |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » order\_by | [groupSorting](https://openvpn.net/as-docs/rest-api/#groupsorting-1) | false | none | specifies by which attribute groups should be sorted |
| » filters | any | false | none | none |
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | object | false | none | none |
| »»» name | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| »» **anonymous** | [commonUserGroupFilters](https://openvpn.net/as-docs/rest-api/#commonusergroupfilters-1) | false | none | filters that can be applied to both user and group requests |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » enumerate\_members | [enumerateMembersParameter](https://openvpn.net/as-docs/rest-api/#enumeratemembersparameter-1) | false | none | if this is set to true the response will also contain a list of all members of the group. Otherwise only a count of the members will be given. |
| » groups | \[[groupname](https://openvpn.net/as-docs/rest-api/#groupname-1)\] | false | none | a list of groups that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that groups that are not found in the backend will be missing from the response. |
| » proplist | [userPropList](https://openvpn.net/as-docs/rest-api/#userproplist-1) | false | none | A list of user properties to request. If this is null then all user properties for the user/group will be returned. Otherwise the list of user properties that should be returned. |
```json
{
"page_size": 0,
"offset": 0,
"sort_by": "asc",
"order_by": "name",
"filters": {
"name": {
"operation": "substring",
"value": "vio"
},
"admin": {
"value": true
},
"autologin": {
"value": true
},
"anywhere": {
"value": "bass",
"fields": []
}
},
"enumerate_members": true,
"groups": [
"string"
],
"proplist": [
"string"
]
}
```
#### accessListRequestParameters
request parameters for the access lists. Name here means: user or group name. Due to way the ACL all represented as strings in the database, sorting and filtering is very limited.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| order\_by | string | false | none | none |
| filters | object | false | none | filters for the access list objects. |
| » internal\_representation | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| » groupname | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| » username | [filterString](https://openvpn.net/as-docs/rest-api/#filterstring-1) | false | none | This specifies that the result should be filtered by this attribute with the specified operation. |
| » object\_type | string | false | none | Only return users or groups in the response. |
| groups | \[[groupname](https://openvpn.net/as-docs/rest-api/#groupname-1)\] | false | none | a list of groups that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that groups that are not found in the backend will be missing from the response. |
| users | \[[username](https://openvpn.net/as-docs/rest-api/#username-1)\] | false | none | a list of usernames that should be fetched. Note, that this list cannot be arbitrarily long as the query to the backend database has a size limit for a query. Note that usernames that are not found in the backend will be missing from the response. |
###### Enumerated Values
| Property | Value |
| --- | --- |
| order\_by | internal\_prop\_representation |
| order\_by | name |
| object\_type | user |
| object\_type | group |
| object\_type | all |
```json
{
"order_by": "internal_prop_representation",
"filters": {
"internal_representation": {
"operation": "substring",
"value": "vio"
},
"groupname": {
"operation": "substring",
"value": "vio"
},
"username": {
"operation": "substring",
"value": "vio"
},
"object_type": "user"
},
"groups": [
"string"
],
"users": [
"niccolo@paganini.it"
]
}
```
#### enumerateMembersParameter
if this is set to true the response will also contain a list of all members of the group. Otherwise only a count of the members will be given.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | boolean | false | none | if this is set to true the response will also contain a list of all members of the group. Otherwise only a count of the members will be given. |
```json
true
```
#### userPropList
A list of user properties to request. If this is null then all user properties for the user/group will be returned. Otherwise the list of user properties that should be returned.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | array,null | false | none | A list of user properties to request. If this is null then all user properties for the user/group will be returned. Otherwise the list of user properties that should be returned. |
```json
[
"string"
]
```
#### DMZIP
a DMZ IP and port that will that will forwarded to the client. This maps to the internal dmz\_ip user property that is formatted as IP\[:proto/start\_port\[-end\_port\]\]
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ip | string | true | none | the external IP address of the Access Server |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol-1) | false | none | specifies a Layer 4 protocol (e.g. udp or tcp) |
| start\_port | integer | false | none | the starting port for the dmz. If not specified all ports will be forwarded |
| end\_port | integer | false | none | the end port of the ports that are being forwarded. If not specified only a single port (the start\_port) is forwarded. |
```json
{
"ip": "123.7.3.1",
"start_port": 7000,
"end_port": 7111,
"protocol": "udp"
}
```
#### IpService
describes an IP UDP/TCP service or an icmp service
##### Properties
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [portRange](https://openvpn.net/as-docs/rest-api/#portrange-1) | false | none | Describes a layer4 (TCP/UDP) port or port-range. protocol may only be udp or tcp |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [icmpService](https://openvpn.net/as-docs/rest-api/#icmpservice-1) | false | none | Describes an icmp service type. protocol is always icmp |
```json
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
```
#### icmpService
Describes an icmp service type. protocol is always icmp
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol-1) | false | none | specifies a Layer 4 protocol (e.g. udp or tcp) |
| type | string | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | icmp-any |
| type | icmp-echo-reply |
| type | icmp-destination-unreachable |
| type | icmp-network-unreachable |
| type | icmp-host-unreachable |
| type | icmp-protocol-unreachable |
| type | icmp-port-unreachable |
| type | icmp-fragmentation-needed |
| type | icmp-source-route-failed |
| type | icmp-network-unknown |
| type | icmp-host-unknown |
| type | icmp-network-prohibited |
| type | icmp-host-prohibited |
| type | icmp-TOS-network-unreachable |
| type | icmp-TOS-host-unreachable |
| type | icmp-communication-prohibited |
| type | icmp-host-precedence-violation |
| type | icmp-precedence-cutoff |
| type | icmp-source-quench |
| type | icmp-redirect |
| type | icmp-network-redirect |
| type | icmp-host-redirect |
| type | icmp-TOS-network-redirect |
| type | icmp-TOS-host-redirect |
| type | icmp-echo-request |
| type | icmp-router-advertisement |
| type | icmp-router-solicitation |
| type | icmp-time-exceeded |
| type | icmp-ttl-zero-during-transit |
| type | icmp-ttl-zero-during-reassembly |
| type | icmp-parameter-problem |
| type | icmp-ip-header-bad |
| type | icmp-required-option-missing |
| type | icmp-timestamp-request |
| type | icmp-timestamp-reply |
| type | icmp-address-mask-request |
```json
{
"protocol": "tcp",
"type": "icmp-any"
}
```
#### portRange
Describes a layer4 (TCP/UDP) port or port-range. protocol may only be udp or tcp
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| protocol | [layer4protocol](https://openvpn.net/as-docs/rest-api/#layer4protocol-1) | true | none | specifies a Layer 4 protocol (e.g. udp or tcp) |
| start\_port | integer | true | none | The start port of the port range |
| end\_port | integer | false | none | The end port of the port range. If not specified, the range will consist of only one single port (start\_port) |
```json
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
```
#### layer4protocol
specifies a Layer 4 protocol (e.g. udp or tcp)
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | string | false | none | specifies a Layer 4 protocol (e.g. udp or tcp) |
###### Enumerated Values
| Property | Value |
| --- | --- |
| **anonymous** | tcp |
| **anonymous** | udp |
| **anonymous** | icmp |
```json
"tcp"
```
#### accessRouteListItem
Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works.
- The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property.
- The user/group require the username/groupname property
- the nat and route type require the subnet property.
Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class.
Either username or groupname is set to indicate whether this is a user or group assigned access rules.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| username | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | none | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| groupname | [groupname](https://openvpn.net/as-docs/rest-api/#groupname-1) | false | none | a group name that is being in used in user management to specify a group name. |
| access\_route | any | false | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | [accessRoute](https://openvpn.net/as-docs/rest-api/#accessroute-1) | false | none | Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works. - The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property. - The user/group require the username/groupname property - the nat and route type require the subnet property. Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class. |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | null | false | none | indicator that routes of this type should be deleted |
continued
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| type | string | false | none | the type of access list this item this is in the user/group. |
oneOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
not
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
xor
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
not
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| » **anonymous** | object | false | none | none |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | access\_from\_ipv6 |
| type | access\_from\_ipv4 |
| type | access\_to\_ipv4 |
| type | access\_to\_ipv6 |
```json
{
"username": "johann",
"access_route": {
"type": "route",
"accept": "true",
"subnet": {
"ipv6": true,
"prefix_length": 64,
"netip": "2001:bach:ce1:10::0"
}
},
"type": "access_to_ipv4"
}
```
#### accessRoute
Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works. - The all, all\_vpn\_clients and all\_s2c\_subnet types do not require an additional property.
- The user/group require the username/groupname property
- the nat and route type require the subnet property.
Note that internally there is also the class subnet and this class can be modified with a R/N suffix to be either the route or nat class, so the API will represent these with the appropriate class.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| type | string | false | none | none |
| accept | boolean | false | none | specifies if we accept or deny this particular access |
| username | [username](https://openvpn.net/as-docs/rest-api/#username-1) | false | none | a username. If this parameter is specified many methods require admin privileges instead normal user privileges if the username is different from the username of the auth token. Note that the backend will treat usernames always case-sensitive in the API |
| groupname | [groupname](https://openvpn.net/as-docs/rest-api/#groupname-1) | false | none | a group name that is being in used in user management to specify a group name. |
| subnet | [accessRouteSubnet](https://openvpn.net/as-docs/rest-api/#accessroutesubnet-1) | false | none | The definition of the subnet used by the nat and route accessRoute classes. Each one is a subnet with one or more port ranges For reference, the internal representation on the Access Server properties looks like this: - 192.168.4.0/24 - 10.10.0.0/24:https,udp/1194,tcp/1194 - 192.168.99.0/24::R - 192.168.99.0/24:https,udp/1194,tcp/1194,udp/2000-2999:R - 2001:608:3:814::0/64 |
###### Enumerated Values
| Property | Value |
| --- | --- |
| type | user |
| type | group |
| type | route |
| type | nat |
| type | all |
| type | all\_vpn\_clients |
| type | all\_s2c\_subnets |
```json
{
"type": "user",
"accept": true,
"username": "niccolo@paganini.it",
"groupname": "string",
"subnet": {
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false,
"service": [
{}
]
}
}
```
#### accessRouteSubnet
The definition of the subnet used by the nat and route accessRoute classes. Each one is a subnet with one or more port ranges
For reference, the internal representation on the Access Server properties looks like this: - 192.168.4.0/24 - 10.10.0.0/24:https,udp/1194,tcp/1194 - 192.168.99.0/24::R - 192.168.99.0/24:https,udp/1194,tcp/1194,udp/2000-2999:R - 2001:608:3:814::0/64\|https,udp/1194,tcp/1194,udp/2000-2999\|R - 10.0.0.7/24:icmp-any,rdp,imaps - 10.0.0.1/25:icmp-TOS-host-redirect
Note that the services array is optional. A missing service array indicates that the whole subnet is affected regardless of the used layer 4 service (icmp, tcp, udp or other IP protocol)
##### Properties
allOf
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | [IPsubNet](https://openvpn.net/as-docs/rest-api/#ipsubnet-1) | false | none | describes an IP subnet. |
and
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| **anonymous** | object | false | none | none |
| » service | \[[IpService](https://openvpn.net/as-docs/rest-api/#ipservice-1)\] | false | none | \[describes an IP UDP/TCP service or an icmp service\] |
```json
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false,
"service": [
{
"protocol": "tcp",
"start_port": 0,
"end_port": 0
}
]
}
```
#### IPsubNet
describes an IP subnet.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 subnet |
| netip | string | false | none | the network IP address. |
| prefix\_length | integer | false | none | length of the prefix in CIDR notation |
```json
{
"prefix_length": 21,
"netip": "131.234.72.0",
"ipv6": false
}
```
#### groupIpRange
An IP Range that describes allowed IP addresses for a group will be represented as on backend as: - “first\_ip-last\_ip” - “first\_ip~numberOfIPs” - “first\_ip:last\_ip” (IPv4 only, deprecated)
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ipv6 | boolean | false | none | whether this describes an IPv4 or an IPv6 range |
| first\_ip | string | false | none | the start address of the IP range. |
| last\_ip | string | false | none | the end address of the IP range. |
```json
{
"ipv6": true,
"first_ip": "fd00::18cc:1b01:a772:50e1",
"last_ip": "fd00::18cc:1b01:a772:80e1"
}
```
#### failOverTestResult
The result of a single failover test.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| friendly | string | false | none | Human readable interpretation of the test |
| status | boolean | true | none | Whether this test succeeded or not |
| message | string | true | none | detailed string of the test result |
```json
{
"friendly": "string",
"status": true,
"message": "string"
}
```
#### failOverTestStatus
The result of running the failover tests. The failover test runs a number of subtests. Note that if the connectivity test fails, often the other tests will fail as well.
##### Properties
| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ucarp | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| license\_primary | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| license\_secondary | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
| connectivity | [failOverTestResult](https://openvpn.net/as-docs/rest-api/#failovertestresult) | false | none | The result of a single failover test. |
```json
{
"ucarp": {
"friendly": "string",
"status": true,
"message": "string"
},
"license_primary": {
"friendly": "string",
"status": true,
"message": "string"
},
"license_secondary": {
"friendly": "string",
"status": true,
"message": "string"
},
"connectivity": {
"friendly": "string",
"status": true,
"message": "string"
}
}
```
## Legacy REST API
### Access Server API
#### Overview
The Access Server REST API allows programmatic download of OpenVPN connection profiles. This is the same API used by OpenVPN Connect and is compatible with other clients and tools.
- Supports **userlogin** and **autologin** profiles.
- Uses **HTTP Basic Authentication**.
- Returns connection profiles as `.ovpn` files.
- Can be accessed via command-line tools like `curl`.
#### Base URL
`https:///rest/`
#### Prerequisites
- Access Server is deployed and accessible.
- XML-RPC/REST API is enabled under: **Admin Web UI \> Configuration \> CWS Settings**.
- A valid **username** and **password** for an Access Server user.
- Access Server’s HTTPS port is typically `443`, unless configured otherwise.
### Authentication
The API uses **HTTP Basic Authentication**. Include the `username:password` pair in your request header or via the `-u` option in `curl`.
TLS certificate validation is required. If using a self-signed certificate, pass it with `--cacert`. Avoid using `-k` unless testing.
**Request**
If your credentials contain special characters (e.g., `@`), wrap them in single quotes.
```
curl -u 'username:password' https:///rest/
```
### Profile Parameters
| **Parameter** | **Description** |
| --- | --- |
| `USERNAME` | The username of the Access Server user for whom the connection profile is requested. |
| `PASSWORD` | The specified user's password. |
| `CWS_PORT` | (Optional) The port on which the client web server listens. This is set to 443 by default, but you can specify a different port if needed. |
| ``` tls-cryptv2 ``` | Indicates support for TLS Crypt V2, a more secure encryption mechanism for protecting control channel traffic in OpenVPN. |
| `deviceID` | Specify the device for which the connection profile is being generated. (It helps associate a particular connection profile with a specific device, ensuring the generated profile corresponds to the right device.) |
### Endpoints
#### GetUserlogin
Retrieves a user-based OpenVPN connection profile (requires username/password at connection time).
Request
```
curl -u 'username:password' "https:///rest/GetUserlogin?tls-cryptv2=1&action=import"
```
##### Optional query parameters
- `tls-cryptv2=1`: Enables TLS Crypt V2 (recommended for enhanced security).
- `action=import`: Triggers direct import in some clients.
##### Optional headers (to prevent multiple 2FA prompts)
`VPN-Session-User: `
`VPN-Session-Token: `
##### Success response
- `Content-Type: application/x-openvpn-profile`
##### Error response:
- `Content-Type: text/xml`
#### GetAutologin
Retrieves a client-certificate-based profile suitable for unattended clients (no password prompt).
> **Important**
>
> Ensure the user has **autologin** permission enabled in the Admin Web UI under **User Permissions**.
Request
```
curl -u 'username:password' https:///rest/GetAutologin
```
##### Success response
- `Content-Type: application/x-openvpn-profile`
##### Error response
- `Content-Type: text/xml`
### Challenge/Response Authentication
#### Overview
The REST API supports challenge/response authentication for cases requiring additional user verification. This method is used when the server needs to verify a user's identity through a challenge that the user must respond to before the requested OpenVPN configuration file can be returned.
Here's an overview of how the process works:
1. The client sends an authentication request with the user's credentials (username and password) to the Access Server:
```
curl -u test:mypass https://ACCESS_SERVER/rest/GetUserlogin
```
2. When additional verification is required (e.g., a Turing test), the server responds with a challenge message instead of the requested configuration file. This response includes the challenge details, formatted as `CRV1`.
3. The client presents the challenge to the user (e.g., "What is 1 x 3?"). The user enters the response.
4. The client then resubmits the request with the challenge response in the format specified by the server.
5. If the server validates the response, the requested connection profile is returned.
#### Challenge/response authentication details
1. **Receiving a challenge:** When the client requests a connection profile (e.g., `GetUserlogin`), but the server needs further validation, it responds with a challenge.
2. **Understanding the challenge message:** The challenge message follows the format `CRV1: :::`, where:
- `flags`: A series of optional, comma-separate flags specifying additional behavior:
- `E`: Echo the response as the user types it.
- `R`: Indicates that a response is required.
- `state_id`: An opaque string to be returned along with the response.
- `username_base64`: The base64-encoded username of the user requesting the connection profile.
- `challenge_text`: The challenge text (e.g., the Turing question) presented to the user.
3. **Responding to the challenge:** After displaying the challenge text to the user, the client waits for the user's response. If the `R` flag is present, the response is required. The response may be an empty string if the flag isn't present.
4. **Resubmitting the response:** Once the user responds, the client resubmits the request to the server.
5. **Validating the response:** If the server successfully validates the response (e.g., '3' as the answer to the Turing test), it returns the requested connection profile, and the client can proceed with the VPN connection.
**Example Challenge**
```
Authorization Required
REST method failed
CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)
```
**Example resubmit with the challenge response**
```
curl -u "test:CRV1::miwN39AlF4k40Fd8X8r9j74FuOoaJKJM::3" https://ACCESS_SERVER/rest/GetUserlogin
```
Here, the `username` is decoded from the `username_base64`, and the `state_id` and `response_text` (the user's answer) are appended.
#### Example workflow
1. Initial request:
```
curl -u test:mypass https://ACCESS_SERVER/rest/GetUserlogin
```
2. Server response (challenge):
```
Authorization Required
REST method failed
CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)
```
3. The user responds to the challenge question, "What is 1x3?" with the answer **3**.
4. The client resubmits the request:
```
curl -u "test:CRV1::miwN39AlF4k40Fd8X8r9j74FuOoaJKJM::3" https://ACCESS_SERVER/rest/GetUserlogin
```
5. The server verifies the response and returns the connection profile.
### Certificate Verification
When using `curl`, ensure that the Access Server web server [employs a trusted certificate](https://openvpn.net/as-docs/tutorials/tutorial--install-ssl-certificate.md), such as a commercial web certificate. If you use a self-signed CA, ensure this certificate is available to `curl` or any HTTPS client you're using.
The Access Server web CA certificate can be found at `/usr/local/openvpn_as/etc/web-ssl/ca.crt`.
You can specify it with a `curl` option:
`--cacert ca.crt`
> **Caution**
>
> While you can disable web server certificate verification using the `-k` option, we discourage this practice for security reasons.
### Error Handling
The REST API will return errors in an **XML format** (in contrast to typical REST JSON responses). These are some common error responses:
- **Authentication failed (invalid username/password):**
```
Authorization Required
REST method failed
AUTH_FAILED: Server Agent XML method requires authentication (9007)
```
- **Permission denied (user lacks autologin privileges):**
```
Internal Server Error
REST method failed
NEED_AUTOLOGIN: User 'USERNAME' lacks autologin privilege (9000)
```
- **User not enrolled for authentication:**
```
Access denied
REST method failed
You must enroll this user in Authenticator first before you are allowed to retrieve a connection profile. (9008)
```
- **WebAuth fallback:** An error will occur if the server is configured for web-based authentication (SAML) but a user attempts to use the REST API instead. The client should offer the option to proceed with SAML authentication.
```
Authorization Required
REST method failed
Ovpn-WebAuth: providername,flags
```
---
Index: https://openvpn.net/as-docs/llms.txt