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.

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

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

Body parameter

{
  "request_admin": true,
  "username": "string",
  "password": "string",
  "totp": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	userAndPwLogin	false	none
» anonymous	body	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	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	Authentication successful. Returns user properties and an auth token.	loginResponse
401	Unauthorized	MFA is required, or SAML login is expected.	Inline
403	Forbidden	Invalid credentials or user access denied.	errorReason
409	Conflict	MFA enrollment is required. Returns an intermediate auth token for enrollment.	loginResponse

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
» MFAChallenge	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "request_admin": true,
  "response": "pa$$word",
  "challenge_context": "FJAIIXMAIOFLGAK23",
  "username": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	MFAResponse	true	none
» anonymous	body	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	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	Authentication successful.	loginResponse
403	Forbidden	Invalid MFA response.	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "request_admin": true,
  "assertion": "string",
  "relay_state": "vpnauth~nod1~Dfk3287761d"
}

Parameters

Name	In	Type	Required	Description
body	body	samlLogin	true	none
» anonymous	body	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	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	Authentication successful.	loginResponse
400	Bad Request	The RelayState is incorrect or the SAML assertion is invalid.	errorReason
401	Unauthorized	The authentication assertion could not be processed: the status was unhandled, unknown, or invalid.	errorReason
403	Forbidden	Access denied due to user/account restrictions, invalid SAML config, or profile requiring user/password based authentication.	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Responses

Status	Meaning	Description	Schema
200	OK	Token renewed successfully.	authTokenResponse
401	Unauthorized	The old token has expired and cannot be renewed.	errorReason
403	Forbidden	Token renewal is no longer allowed.	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "auth_token": "string",
  "expires_after": "string",
  "renewable_until": "string"
}

changePasswordLocalUser

Body parameter

{
  "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	Password changed successfully.	Inline
401	Unauthorized	Authentication failed.	Inline
403	Forbidden	Auth token is not recent enough, or the new password does not meet security requirements.	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

RequestJavaScript

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);
});

Responsejson

{
  "detail": "string"
}

enrollUserMFA

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	MFA enrollment was successful.	Inline
400	Bad Request	Provided MFA token is invalid or enrollment failed for another reason.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Responses

Status	Meaning	Description	Schema
200	OK	Installer file downloaded successfully.	string
400	Bad Request	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	The requested installer file was not found on the server, or an unexpected error occurred while downloading.	None

RequestJavaScript

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	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

Responses

Status	Meaning	Description	Schema
200	OK	Connection profile downloaded successfully.	string
400	Bad Request	An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used.	Inline

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

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	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

Responses

Status	Meaning	Description	Schema
200	OK	Responds with connection profile file	string
400	Bad Request	An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used.	Inline

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

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	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

Responses

Status	Meaning	Description	Schema
200	OK	Userlogin connection profile downloaded successfully.	string
400	Bad Request	An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used.	Inline

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

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	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

Responses

Status	Meaning	Description	Schema
200	OK	Generic profile downloaded successfully.	string
400	Bad Request	An XMLRPC-style error response for compatibility with older /rest APIs. For compatibility reasons this way of reporting errors is used.	Inline

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

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

Body parameter

[
  "string"
]

Parameters

Name	In	Type	Required	Description
body	body	array[string]	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Token were successfully deleted	None
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	One or more token IDs were not found. No tokens were deleted.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Redirects to base server URL with headers in the response according to OpenVPN webauth API specification.	None

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Redirect to http://server_addres/login?relay_state=profile	None

This operation does not require authentication

RequestJavaScript

fetch('/api/openvpn-api/profile',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

getprofilesuser

Body parameter

{
  "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	false	none

Responses

Status	Meaning	Description	Schema
200	OK	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	false	none	none
»»» serial	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	true	none	The certificate common name (CN).
»»» algorithm	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	false	none
» username	body	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	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	Profile created successfully.	string
403	Forbidden	Profile creation not permitted.	errorReason

Response Headers

Status	Header	Type	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

RequestJavaScript

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

Body parameter

{
  "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	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	true	Specifies the connection profile type.
» username	body	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Token URL generated successfully.	string
400	Bad Request	Token url could not be generated.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	List of all valid profile token URLs.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» profileTokens	[profileToken]	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	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

RequestJavaScript

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);
});

Responsejson

{
  "profileTokens": [
    {
      "token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
      "username": "arne@openvpn.net",
      "expires": "2019-08-24T14:15:22Z",
      "profile_type": "autologin",
      "usages": 1,
      "comment": "connected from my iPhone"
    }
  ]
}

deleteProfileSerial

Parameters

Name	In	Type	Required	Description
serial	path	certificateSerial	true	none

Responses

Status	Meaning	Description	Schema
200	OK	Profiles were successfully deleted.	Inline
400	Bad Request	The profile could not be deleted.	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

RequestJavaScript

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);
});

Responsejson

{
  "message": "string"
}

deleteProfileUser

Body parameter

{
  "users": [
    "niccolo@paganini.it"
  ],
  "filter": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» users	body	[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	Profiles were successfully deleted.	Inline
400	Bad Request	The user profiles were not deleted.	errorReason
404	Not Found	The user profiles were not found.	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

RequestJavaScript

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);
});

Responsejson

{
  "message": "string"
}

deleteProfile

Body parameter

[
  "1708464983752887'"
]

Parameters

Name	In	Type	Required	Description
body	body	certificateSerial	false	none

Responses

Status	Meaning	Description	Schema
200	OK	The request was successfully executed. The status for each profile is included in the response.	Inline
400	Bad Request	could not delete the profile	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	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

RequestJavaScript

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);
});

Responsejson

{
  "message": null,
  "response": {
    "21": 204,
    "7127317": 404
  }
}

vpnca

Endpoints for managing the certificate authorities (CAs) used to sign VPN server and client certificates.

getVPNCas

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful. The response includes an array of CAs with details.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[allOf]	false	none	none

allOf

Name	Type	Required	Restrictions	Description
» anonymous	certificateDetails	false	none	none
»» serial	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	true	none	The certificate common name (CN).
»» algorithm	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	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

RequestJavaScript

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);
});

Responsejson

[
  {
    "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

Body parameter

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA"
}

Parameters

Name	In	Type	Required	Description
body	body	certificateRequest	false	none
» algorithm	body	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	false	The certificate common name (CN).

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	The new CA was successfully created	None
400	Bad Request	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
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

delete_ca_vpn{serial}

Responses

Status	Meaning	Description	Schema
200	OK	The CA was successfully deleted	None
400	Bad Request	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
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	The specified CA was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
serial	path	certificateSerial	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.

{
  "message": "Insufficient privileges to use this API"
}

CaSupportedAlgorithms

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returns a list of allowed public/private key algorithms.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[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

RequestJavaScript

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);
});

Responsejson

[
  "rsa2048",
  "rsa3072",
  "rsa4096",
  "ed448",
  "brainpoolP384r1",
  "brainpoolP512r1",
  "secp2256k1",
  "Ed25519"
]

info

Endpoints for querying various aspects of the running server and its current status.

certificateInfo

Body parameter

{
  "certificate": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» certificate	body	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	Returns detailed information about the X509 certificate.	certificateInformationDetails
400	Bad Request	The provided certificate could not be parsed, or encountered other problems.	errorReason
403	Forbidden	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Both the private key and certificate were successfully parsed. The response indicates whether the private key matches the certificate.	Inline
400	Bad Request	The certificate or private key could not be parsed.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	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

RequestJavaScript

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);
});

Responsejson

{
  "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

{
  "certificate": "string",
  "chain": "string",
  "ca_roots": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	The certificate has been successfully verified against the provided CA certificates. The response contains the trust chain that was found.	Inline
400	Bad Request	The certificate failed verification. Details are provided in the response.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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(pem)	true	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.
» chain	body	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]	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.

{
  "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	false	none	none
»»» serial	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	true	none	The certificate common name (CN).
»»» algorithm	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(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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returns the current EULA, its version, and whether the user has accepted it.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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

Parameters

Name	In	Type	Required	Description
no_loopback	query	boolean	false	if true exclude loopback interfaces

Responses

Status	Meaning	Description	Schema
200	OK	A list of network interfaces and their assigned IP and IPv6 addresses.	Inline
403	Forbidden	User does not have admin permission	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[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]	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

RequestJavaScript

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);
});

Responsejson

[
  {
    "name": "eth0",
    "networks": [
      {},
      {},
      {}
    ]
  }
]

get__server_info

Responses

Status	Meaning	Description	Schema
200	OK	Returns information about the running Access Server instance.	serverInfo
403	Forbidden	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

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	DNS servers	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

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);
});

Responsejson

[
  {
    "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returns the DCO module status and version.	dcoModuleStatus
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "available": true,
  "version": "0.2.20230323"
}

post__helper_status-overview

Body parameter

{
  "names": [
    "vpn.server.cipher"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Consolidated status overview data.	Inline
400	Bad Request	Something went wrong	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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]	false	list of configuration items that should be retrieve from the active configuration

standard response when there insufficient rights to use an API.

{
  "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	true	none	The configuration value's key.
»»»» derived_from	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	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	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	false	none	A configuration value that is expressed as an integer.

allOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	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	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	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	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	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	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	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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Licensing information for the Access Server instance.	licenseInfo
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "licensing_type": "unlicensed",
  "current_cc": 3,
  "max_cc": 13,
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

checkSubscription

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription test result returned successfully.	subscriptionInfo
400	Bad Request	The license key format is invalid, or an error occurred while processing the test.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription has been successfully loaded.	None
400	Bad Request	The license key format is invalid, or an error occurred while applying the subscription.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

deactivateSubscription

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription has been successfully deactivated.	None
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "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.

{
  "message": "License not found on server"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Fixed license key successfully activated.	None
400	Bad Request	The license format is invalid, or an error occurred during activation.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
503	Service Unavailable	License server is unreachable.	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

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.

{
  "message": "Fixed license already expired"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Fixed license key has been successfully activated.	None
400	Bad Request	The license format is invalid, or an error occurred during activation.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Machine ID file returned successfully.	string
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsetext

"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	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
504	Gateway Time-out	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

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	List of cluster nodes.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	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	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	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(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

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The cluster DNS hostname was updated successfully on all nodes.	None
400	Bad Request	Failed to update the cluster DNS hostname due to a configuration error.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

clustergetprops

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved cluster properties from the cluster	Inline
400	Bad Request	Getting the cluster properties failed	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "rr_dns_hostname": "cluster.example.com",
  "rr_dns_new_nodes": true
}

Parameters

Name	In	Type	Required	Description
body	body	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.

{
  "message": "rr_dns_hostname has invalid characters in it"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The cluster properties were successfully updated in the database.	None
400	Bad Request	Setting the cluster properties failed.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "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	The server successfully joined the cluster.	None
400	Bad Request	The server failed to join the cluster.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeJoinRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__cluster_create

Body parameter

{
  "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	The cluster was created and the current node joined successfully.	None
400	Bad Request	The cluster could not be created.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeCreateRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__cluster_leave

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The node was successfully removed from the cluster.	None
400	Bad Request	The request to leave the cluster failed.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

put__database_convert

Body parameter

{
  "host": "string",
  "port": 1,
  "username": "string",
  "password": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	The database was successfully converted, and the configuration updated.	None
400	Bad Request	The database conversion failed.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	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.

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Support report generated successfully. The output is the same as running `sacli support`.	string
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsetext

"string"

post__server_restart

Responses

Status	Meaning	Description	Schema
200	OK	Server restart successfully scheduled	None
400	Bad Request	Server has some misconfiguration and restart is not scheduled	errorReasonDetail
403	Forbidden	User does not have admin permission	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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	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

Responses

Status	Meaning	Description	Schema
200	OK	Server and status returned successfully	serverStatus
403	Forbidden	User does not have admin permission	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	A list of all configuration profiles on Access Server	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» active_profile	configurationProfile	false	none	The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups.
» profiles	[configurationProfile]	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

RequestJavaScript

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);
});

Responsejson

{
  "active_profile": "default",
  "profiles": [
    "default",
    "heaven",
    "hades",
    "olymp"
  ]
}

configurationProfileDelete

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Configuration profile was successfully deleted	None
400	Bad Request	profile deletion would violate some constraints like deleting the active profile	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	Specified configuration profile was not found.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

configurationProfileCreate

Body parameter

{
  "profile": "string",
  "copy_from": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» profile	body	configurationProfile	true	The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups.
» copy_from	body	configurationProfile	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	The configuration profile was created successfully.	None
400	Bad Request	The profile name is invalid, or another error occurred during creation.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	The specified `copy_from` configuration profile does not exist.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

validateConfigProfile

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The configuration profile is valid with no detected errors.	None
400	Bad Request	The profile contains validation issues.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	Configuration profile does not exist.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

RunSetActiveProfile

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	The name of the profile to activate.
restartMode	query	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success. No errors in the profile are detected and the new profile is being set.	None
400	Bad Request	validation of the profile encountered some problems or some other error occurred. See error reason for more details.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	the requested configuration profile was not found.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "names": [
    "vpn.server.cipher"
  ],
  "include_pattern_keys": false
}

Parameters

Name	In	Type	Required	Description
configurationProfile	path	configurationProfile	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The list of configuration items was successfully returned.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	Configuration profile does not exist.	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	true	none	The configuration value's key.
»»» derived_from	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	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	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	false	none	A configuration value that is expressed as an integer.

allOf

Name	Type	Required	Restrictions	Description
»»»» anonymous	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	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	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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}

Body parameter

{
  "property1": "string",
  "property2": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Configuration items were updated successfully.	None
400	Bad Request	One or more configuration values are invalid; no changes were made.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	Configuration profile does not exist.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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	true	none
body	body	object	true	none
» additionalProperties	body	string	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

saml

Endpoints for managing SAML-based authentication flow.

post__saml_acs

Body parameter

RelayState: string
SAMLResponse: string

Responses

Status	Meaning	Description	Schema
200	OK	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	Returned when the request is invalid or the assertion cannot be validated.	None
405	Method Not Allowed	Only POST requests are allowed at this endpoint.	None

RequestJavaScript

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 vpnauth_nodeidsessionid
» 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.

"< <head> <javascript> SAMLResponse = \"[samlassertion data]\"; RelayState = \"cwslogin\"; </javascript> [content of index.html]"

Returned when the request is invalid or the assertion cannot be validated.

"< <head>HEAD content</head> <body><h1>SAML authentication failed</h1><p>assertion request is invalid</p></body>"

Only POST requests are allowed at this endpoint.

"< <head>HEAD content</head> <body><h1>SAML authentication failed</h1><p>assertion method is not supported</p></body>"

Response Schema

This operation does not require authentication

get__saml_metadata

SAML is not configured, or the configuration is invalid.

"< <head>HEAD content</head> <body><h1>404 Not Found</h1><p>SAML not configured or invalid configuration</p></body>"

Responses

Status	Meaning	Description	Schema
200	OK	Returns the XML metadata for the Access Server SAML Service Provider.	string
404	Not Found	SAML is not configured, or the configuration is invalid.	None

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Redirects the client to the SAML IdP URL.	None

This operation does not require authentication

RequestJavaScript

fetch('/api/saml/redirect',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

get__auth_get-idp-url

Responses

Status	Meaning	Description	Schema
200	OK	Returns the IdP URL to redirect the user for SAML authentication.	string
400	Bad Request	RelayState invalid or SAML configuration error.	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	The SAML assertion was forwarded successfully.	None
400	Bad Request	The assertion was invalid, such as an empty string or a malformed request.	errorReason
401	Unauthorized	The relay state is incorrect, or the assertion was rejected.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

get__vpn_status

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returns the VPN server status and client connection details.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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	false	none	none
»»» daemon_id	daemonID	true	none	An ID that identifies the specific OpenVPN daemon the client is connected to.
»»» client_id	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	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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The specified client(s) were disconnected successfully.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	The specified client could not be found by daemon and client ID.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "user": "niccolo@paganini.it",
  "installer_type": "win_v3",
  "profile_type": "autologin",
  "tls_crypt_v2": true
}

Parameters

Name	In	Type	Required	Description
body	body	installerProfileRequest	false	none
» user	body	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	true	Specifies the type of the installer binary to be generated.
» profile_type	body	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	Installer URL was successfully generated.	string
400	Bad Request	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

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved the default user configuration.	userPropUserDefault
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully returned user profiles.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	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	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	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	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	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	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	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	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	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	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	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	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	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]	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	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]	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	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]	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]	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	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.<win
»»» cli_script_connect_win_user_connect	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	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	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	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	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	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	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	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	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	false	none	This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source.

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration
mfa_status	pending
mfa_status	disabled
mfa_status	enrolled
protocol	tcp
protocol	udp
protocol	icmp

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "total": 0,
  "profiles": [
    {
      "name": "string",
      "deny": {},
      "deny_web": {},
      "admin": {},
      "autologin": {},
      "auth_method": {},
      "cc_commands": {},
      "totp": {},
      "password_strength": {},
      "allow_password_change": {},
      "reroute_gw": {},
      "allow_generate_profiles": {},
      "bypass_subnets": [],
      "password_defined": true,
      "mfa_status": "pending",
      "totp_locked": true,
      "group": "stringsection",
      "static_ipv4": "string",
      "static_ipv6": "string",
      "dmz_ip": [],
      "dmz_ipv6": [],
      "compile": true,
      "totp_secret": "string",
      "totp_admin_only": true,
      "client_to_server_subnets": [],
      "cli_script_connect_win_user_connect": {},
      "cli_script_connect_win_user_disconnect": {},
      "cli_script_connect_win_admin_connect": {},
      "cli_script_connect_win_admin_disconnect": {},
      "cli_script_connect_mac_user_connect": {},
      "cli_script_connect_mac_user_disconnect": {},
      "cli_script_connect_mac_admin_connect": {},
      "cli_script_connect_mac_admin_disconnect": {},
      "cli_script_connect_win_env": {},
      "cli_script_connect_mac_env": {}
    }
  ]
}

createUserPropUser

Body parameter

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	userPropUserSet	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	New user has been created successfully.	None
400	Bad Request	The user already exists, contains invalid characters, a group with the same name exists, or one of the specified user properties is invalid.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

createUserPropGroup

Body parameter

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	userPropGroupSet	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	New group has been successfully created	None
400	Bad Request	The group already exists, contains invalid characters, conflicts with an existing user name, or includes invalid property values.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

listAccessLists

Body parameter

{
  "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"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	accessListRequestParameters	false	none
» order_by	body	string	false	none
» filters	body	object	false	filters for the access list objects.
»» internal_representation	body	filterString	false	Specifies a filter for string-based attributes using a defined operation.
»»» value	body	string	true	none
»»» operation	body	string	true	none
»» groupname	body	filterString	false	Specifies a filter for string-based attributes using a defined operation.
»» username	body	filterString	false	Specifies a filter for string-based attributes using a defined operation.
»» object_type	body	string	false	Only return users or groups in the response.
» groups	body	[groupname]	false	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	body	[username]	false	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

Parameter	Value
» order_by	internal_prop_representation
» order_by	name
»»» operation	equal
»»» operation	substring
»»» operation	not_equal
»» object_type	user
»» object_type	group
»» object_type	all

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

A list of all matching access lists

Name	Type	Required	Restrictions	Description
» profiles	[oneOf]	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. Either username or groupname is set to indicate whether this is a user or group assigned access rules. ]
»» username	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	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	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.
»»»» type	string	false	none	none
»»»» accept	boolean	false	none	specifies if we accept or deny this particular access
»»»» username	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	false	none	Name of a user group used in user management. specify a group name.
»»»» subnet	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

allOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	object	false	none	Describes an IP subnet.
»»»»»» 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	object	false	none	none
»»»»»» service	[oneOf]	false	none	[Describes a network service using an IP protocol — either TCP, UDP, or ICMP.]

oneOf

Name	Type	Required	Restrictions	Description
»»»»»»» anonymous	portRange	false	none	Describes a layer 4 TCP or UDP port or port-range. The protocol must be either udp or tcp.
»»»»»»»» protocol	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)

xor

Name	Type	Required	Restrictions	Description
»»»»»»» anonymous	icmpService	false	none	Describes an ICMP service type. The protocol property value is always ICMP.
»»»»»»»» protocol	layer4protocol	false	none	Specifies a Layer 4 protocol such as udp or tcp.
»»»»»»»» type	string	false	none	none

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	user
type	group
type	route
type	nat
type	all
type	all_vpn_clients
type	all_s2c_subnets
protocol	tcp
protocol	udp
protocol	icmp
protocol	tcp
protocol	udp
protocol	icmp
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
type	access_from_ipv6
type	access_from_ipv4
type	access_to_ipv4
type	access_to_ipv6

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/access/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

setAccessLists

Body parameter

{
  "items_set": [
    {
      "username": "johann",
      "access_route": {}
    },
    {
      "username": "wolfgang",
      "access_route": null,
      "type": "access_to_ipv4"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» items_set	body	array	false	none
»» username	body	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.
»» groupname	body	groupname	false	Name of a user group used in user management. specify a group name.
»» access_route	body	any	false	none
»»» anonymous	body	accessRoute	false	Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works.
»»»» type	body	string	false	none
»»»» accept	body	boolean	false	specifies if we accept or deny this particular access
»»»» username	body	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.
»»»» groupname	body	groupname	false	Name of a user group used in user management. specify a group name.
»»»» subnet	body	accessRouteSubnet	false	The definition of the subnet used by the nat and route accessRoute classes.
»»»»» anonymous	body	object	false	Describes an IP subnet.
»»»»»» ipv6	body	boolean	false	whether this describes an IPv4 or an IPv6 subnet
»»»»»» netip	body	string	false	the network IP address.
»»»»»» prefix_length	body	integer	false	length of the prefix in CIDR notation
»»»»» anonymous	body	object	false	none
»»»»»» service	body	[oneOf]	false	[Describes a network service using an IP protocol — either TCP, UDP, or ICMP.]
»»»»»»» anonymous	body	portRange	false	Describes a layer 4 TCP or UDP port or port-range. The protocol must be either udp or tcp.
»»»»»»»» protocol	body	layer4protocol	true	Specifies a Layer 4 protocol such as udp or tcp.
»»»»»»»» start_port	body	integer	true	The start port of the port range
»»»»»»»» end_port	body	integer	false	The end port of the port range. If not specified, the range will consist of only one single port (start_port)
»»»»»»» anonymous	body	icmpService	false	Describes an ICMP service type. The protocol property value is always ICMP.
»»»»»»»» protocol	body	layer4protocol	false	Specifies a Layer 4 protocol such as udp or tcp.
»»»»»»»» type	body	string	false	none
»»» anonymous	body	null	false	indicator that routes of this type should be deleted
»» type	body	string	false	the type of access list this item this is in the user/group.
»» anonymous	body	object	false	none
»»» anonymous	body	object	false	none
»» anonymous	body	object	false	none
»»» anonymous	body	object	false	none

Detailed descriptions

»»» anonymous: 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.

»»»» subnet: 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)

Enumerated Values

Parameter	Value
»»»» type	user
»»»» type	group
»»»» type	route
»»»» type	nat
»»»» type	all
»»»» type	all_vpn_clients
»»»» type	all_s2c_subnets
»»»»»»»» protocol	tcp
»»»»»»»» protocol	udp
»»»»»»»» protocol	icmp
»»»»»»»» protocol	tcp
»»»»»»»» protocol	udp
»»»»»»»» protocol	icmp
»»»»»»»» 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
»» type	access_from_ipv6
»» type	access_from_ipv4
»» type	access_to_ipv4
»» type	access_to_ipv6

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully set or removed access rules.	None
400	Bad Request	The request was malformed or referenced users/groups do not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "items_set": [
    {
      "username": "johann",
      "access_route": {}
    },
    {
      "username": "wolfgang",
      "access_route": null,
      "type": "access_to_ipv4"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/access/set',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

listAccessRulesets

Body parameter

{
  "owner": "openvpn",
  "filters": {
    "name": {
      "operation": "substring",
      "value": "wheel"
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» owner	body	string	false	The assignee username, groupname, or “DEFAULT” for the global ruleset.
» filters	body	object	false	The string filter to be applied to the ruleset name.
»» name	body	filterString	false	Specifies a filter for string-based attributes using a defined operation.
»»» value	body	string	true	none
»»» operation	body	string	true	none

Enumerated Values

Parameter	Value
»»» operation	equal
»»» operation	substring
»»» operation	not_equal

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful.	Inline
400	Bad Request	The request was malformed or referenced users/groups do not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» rulesets	[accessControlResponseRuleset]	true	none	Array of rulesets assigned to the ‘owner’ given in the request.
»» 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.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "owner": "openvpn",
  "filters": {
    "name": {
      "operation": "substring",
      "value": "wheel"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rulesets/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

addAccessRulesets

Body parameter

{
  "name": "NATed Domains",
  "comment": "updated 14.03.2025"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» name	body	string	true	The name of the ruleset.
» comment	body	string	true	The comment for the ruleset.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The ruleset was added successfully.	Inline
400	Bad Request	The request was malformed.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	integer	true	none	The ID assigned to the new ruleset.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "name": "NATed Domains",
  "comment": "updated 14.03.2025"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rulesets/add',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "id": 236
}

updateAccessRulesets

Body parameter

{
  "id": 236,
  "name": "NAT'd Domains",
  "comment": "updated 19.03.2025"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» id	body	integer	true	The ID of the ruleset to update.
» name	body	string	true	The updated name of the ruleset.
» comment	body	string	true	The updated comment for the ruleset.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The ruleset was updated successfully.	None
400	Bad Request	The request was malformed or referenced ruleset does not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "id": 236,
  "name": "NAT'd Domains",
  "comment": "updated 19.03.2025"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rulesets/update',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

deleteAccessRulesets

Body parameter

{
  "ids": [
    236,
    44
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» ids	body	[integer]	true	Array of IDs of the rulesets to delete.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The ruleset was deleted successfully or did not exist in the first place.	None
400	Bad Request	The request was malformed or referenced ruleset does not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "ids": [
    236,
    44
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rulesets/delete',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

modifyAccessUserRulesets

Body parameter

{
  "add": {
    "bernd": [
      {},
      {}
    ]
  },
  "delete": {
    "bernd": {
      "ruleset_ids": []
    },
    "amira": {
      "ruleset_ids": []
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» add	body	userRulesetsAddMap	false	Ruleset mappings for a subject. The subject name is given as the key.
»» additionalProperties	body	[object]	false	List of rulesets to map to the subject
»»» ruleset_id	body	integer	true	The ID of the ruleset to associate with the subject.
»»» position	body	integer	true	Position of the ruleset within all subject’s sets. Sorted ascending.
» delete	body	userRulesetsDeleteMap	false	Ruleset mappings to delete for a subject. The subject name is given as the key.
»» additionalProperties	body	object	false	none
»»» ruleset_ids	body	[integer]	false	A list of ruleset IDs to delete for the subject..

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The mappings were modified.	None
400	Bad Request	The request was malformed or referenced ruleset does not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "add": {
    "bernd": [
      {},
      {}
    ]
  },
  "delete": {
    "bernd": {
      "ruleset_ids": []
    },
    "amira": {
      "ruleset_ids": []
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/user-rulesets/modify',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

listAccessRules

Body parameter

{
  "filters": {
    "type": {
      "operation": "equal",
      "value": "domain_routing"
    },
    "match_type": {
      "operation": "not_equal",
      "value": "domain_or_subdomain"
    },
    "match_data": {
      "operation": "substring",
      "value": "doggo"
    }
  },
  "ruleset_ids": [
    1
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» ruleset_ids	body	[integer]	true	The IDs of the rulesets to list the rules for.
» filters	body	object	false	none
»» type	body	filterAccessRuleType	false	Specifies a filter for access control rule types.
»»» value	body	accessControlRuleTypeEnum	true	Rules can have one of these types.
»»» operation	body	string	true	none
»» match_type	body	filterAccessRuleMatchType	false	Specifies a filter for access control rule match types.
»»» value	body	accessControlRuleMatchTypeEnum	true	Rules can have one of these match types.
»»» operation	body	string	true	none
»» match_data	body	filterString	false	Specifies a filter for string-based attributes using a defined operation.
»»» value	body	string	true	none
»»» operation	body	string	true	none

Enumerated Values

Parameter	Value
»»» value	domain_routing
»»» value	filter
»»» operation	equal
»»» operation	not_equal
»»» value	domain
»»» value	not_domain
»»» value	subdomain
»»» value	not_subdomain
»»» value	domain_or_subdomain
»»» value	not_domain_or_subdomain
»»» operation	equal
»»» operation	not_equal
»»» operation	equal
»»» operation	substring
»»» operation	not_equal

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The rules were retrieved successfully.	Inline
400	Bad Request	The request was malformed or referenced ruleset does not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» rules	[existingAccessControlRule]	true	none	The list of rules requested.
»» id	integer	true	none	The rule ID.
»» ruleset_id	integer	true	none	The ID of the ruleset this rule is assigned to.
»» type	accessControlRuleTypeEnum	true	none	Rules can have one of these types.
»» match_type	accessControlRuleTypeEnum	true	none	Rules can have one of these types.
»» match_data	string	true	none	The match data.
»» action	accessControlRuleActionEnum	true	none	Rules can have one of these actions.
»» 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.

Enumerated Values

Property	Value
type	domain_routing
type	filter
match_type	domain_routing
match_type	filter
action	route
action	nat
action	deny
action	bypass

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "filters": {
    "type": {
      "operation": "equal",
      "value": "domain_routing"
    },
    "match_type": {
      "operation": "not_equal",
      "value": "domain_or_subdomain"
    },
    "match_data": {
      "operation": "substring",
      "value": "doggo"
    }
  },
  "ruleset_ids": [
    1
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rules/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

modifyAccessRules

Body parameter

{
  "add": [
    {
      "id": 1,
      "ruleset_id": 1,
      "type": "domain_routing",
      "match_type": "domain_or_subdomain",
      "match_data": "doggo.com",
      "action": "deny",
      "position": 10000,
      "comment": "my cat's favorite rule"
    },
    {
      "ruleset_id": 1,
      "type": "domain_routing",
      "match_type": "domain",
      "match_data": "abuse.doggo.com",
      "action": "route",
      "position": 5000,
      "comment": "my cat's fine with this"
    }
  ],
  "delete": [
    2,
    3
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» add	body	[oneOf]	false	A list of new or updated rules.
»» anonymous	body	newAccessControlRule	false	Represents a new access control rule.
»»» ruleset_id	body	integer	true	The ID of the ruleset this rule is assigned to.
»»» type	body	accessControlRuleTypeEnum	true	Rules can have one of these types.
»»» match_type	body	accessControlRuleTypeEnum	true	Rules can have one of these types.
»»» match_data	body	string	true	The match data.
»»» action	body	accessControlRuleActionEnum	true	Rules can have one of these actions.
»»» position	body	integer	true	The position of this rule within the other rules in the ruleset.
»»» comment	body	string	true	Free text comment assigned to this rule.
»» anonymous	body	existingAccessControlRule	false	Represents an existing access control rule.
»»» id	body	integer	true	The rule ID.
»»» ruleset_id	body	integer	true	The ID of the ruleset this rule is assigned to.
»»» type	body	accessControlRuleTypeEnum	true	Rules can have one of these types.
»»» match_type	body	accessControlRuleTypeEnum	true	Rules can have one of these types.
»»» match_data	body	string	true	The match data.
»»» action	body	accessControlRuleActionEnum	true	Rules can have one of these actions.
»»» position	body	integer	true	The position of this rule within the other rules in the ruleset.
»»» comment	body	string	true	Free text comment assigned to this rule.
» delete	body	[integer]	false	none

Enumerated Values

Parameter	Value
»»» type	domain_routing
»»» type	filter
»»» match_type	domain_routing
»»» match_type	filter
»»» action	route
»»» action	nat
»»» action	deny
»»» action	bypass
»»» type	domain_routing
»»» type	filter
»»» match_type	domain_routing
»»» match_type	filter
»»» action	route
»»» action	nat
»»» action	deny
»»» action	bypass

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The rules were modified successfully.	Inline
400	Bad Request	The request was malformed or referenced ruleset does not exist.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» added	[integer]	true	none	The list of IDs for added / updated rules. They appear in the same order as the rules were in the request.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "add": [
    {
      "id": 1,
      "ruleset_id": 1,
      "type": "domain_routing",
      "match_type": "domain_or_subdomain",
      "match_data": "doggo.com",
      "action": "deny",
      "position": 10000,
      "comment": "my cat's favorite rule"
    },
    {
      "ruleset_id": 1,
      "type": "domain_routing",
      "match_type": "domain",
      "match_data": "abuse.doggo.com",
      "action": "route",
      "position": 5000,
      "comment": "my cat's fine with this"
    }
  ],
  "delete": [
    2,
    3
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/access/rules/modify',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

post__users_delete

Body parameter

{
  "users": [
    "niccolo@paganini.it"
  ]
}

Responses

Status	Meaning	Description	Schema
204	No Content	Userprop was deleted successfully.	None
400	Bad Request	Invalid request arguments.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	The specified userprop entry does not exist.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "users": [
    "niccolo@paganini.it"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/delete',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
» users	body	[username]	false	users name list to delete.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__groups_delete

Body parameter

{
  "groups": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
204	No Content	Group userprop was deleted successfully.	None
400	Bad Request	Invalid request arguments.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	The specified group userprop entry does not exist.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "groups": [
    "string"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/delete',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
» groups	body	[groupname]	false	users name list to delete.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

modifyUserPropGroupBulk

Body parameter

"[{ 'name': 'bob', 'auth_method': 'saml'}, {'name': 'bob', 'autologin': false, pw_strength: null }]"

Parameters

Name	In	Type	Required	Description
body	body	array[any]	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	User property changes applied successfully.	None
400	Bad Request	One or more properties are invalid, improperly typed (boolean vs string), or not applicable (group only attribute on a user or vice versa) to the specified user(s).	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	user or group does not exist	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '[{ 'name': 'bob', 'auth_method': 'saml'}, {'name': 'bob', 'autologin': false, pw_strength: null }]';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/set',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

helper

These endpoints provide utility functions that simplify specific tasks. While their functionality could be replicated with frontend logic or multiple backend calls, they exist to streamline workflows or avoid redundant implementations, such as parsing SAML metadata on the client side.

post__helper_get-saml-configuration

Body parameter

{
  "data": "string",
  "url": "http://example.com"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully parsed and returned SAML configuration items.	Inline
400	Bad Request	Something went wrong parsing the data or fetching the metadata	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

const inputBody = '{
  "data": "string",
  "url": "http://example.com"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/helper/get-saml-configuration',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "configuration_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
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» data	body	string	false	The string that contains SAML Idp metadata in xml format
» url	body	string(uri)	false	the url from which the backend will fetch SAML Idp metadata from
» anonymous	body	object	false	none
» anonymous	body	object	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» configuration_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	true	none	The configuration value's key.
»»» derived_from	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	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	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	false	none	A configuration value that is expressed as an integer.

allOf

Name	Type	Required	Restrictions	Description
»»»» anonymous	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	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	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	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

certificate

Endpoints for certificate management tasks, such as parsing certificates or retrieving certificate metadata.

post__certificate_create

Body parameter

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Certificate has been generated.	Inline
400	Bad Request	there was some error while trying to generate the certificate	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

const inputBody = '{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/certificate/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "certificate": "string",
  "private_key": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	certificateCreateRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» certificate	pemEncodedCertificate(pem)	false	none	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.
» private_key	pemEncodedPrivateKey(pem)	false	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-----`.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

logs

Endpoints for querying the Access Server log database.

getLogReports

Body parameter

{
  "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": []
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	logDBRequestParameters	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully returns log report entries.	Inline
400	Bad Request	Invalid filter format.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» records	[logDBRecord]	false	none	none
»» timestamp	string(date-time)	true	none	record modification timestamp
»» node	any	true	none	AS node that created the log report
»» username	any	false	none	username that created the entry
»» start_time	any	false	none	start time of the event or just time of the event if duration is missing
»» duration	integer,null	false	none	duration of the event in seconds
»» service	string	false	none	the service of OpenVPN Access Server that created the event
»» active	boolean	false	none	if the session is still active
»» auth	boolean	false	none	whether authentication succeeded or not
»» platform	any	false	none	the platform of the client.
»» version	any	false	none	the version of the OpenVPN component that implement the OpenVPN protocol
»» protocol	string	false	none	the protocol being used
»» gui_version	any	false	none	the IV_GUI version the client reported.
»» real_address	string	false	none	the IP address the client is connected from
»» server_port	integer	false	none	the server side port the client connects/connected to
»» virtual_ipv4_address	string	false	none	the virtual or VPN address of the client
»» virtual_ipv6_address	string	false	none	none
»» session_id	string	false	none	internal session ID of the connection (this might be truncated)
»» api_method	string	false	none	description of the API method that was called
»» bytes_sent	integer	false	none	number of bytes sent
»» bytes_received	integer	false	none	number of bytes received
»» total_bytes	integer	false	none	total number of transferred bytes. (This seems and probably is redundant but currently we keep this as individual record in the backend database)
»» error	string	false	none	error message on auth failure
»» extra	string	false	none	service-specific data
» total	integer	false	none	total number of profiles that match if pagination is not in effect, this matches the size of the provided array

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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": []
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/log/reports',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "records": [
    {
      "timestamp": "2019-08-24T14:15:22Z",
      "node": "vpn-12.example.com",
      "username": null,
      "start_time": null,
      "duration": 0,
      "service": "WEB_ADMIN",
      "active": true,
      "auth": true,
      "platform": "android",
      "version": "2.6.11",
      "protocol": "tcp",
      "gui_version": "de.blinkt.openvpn_0.7.48",
      "real_address": "1.2.7.8:23123",
      "server_port": 1194,
      "virtual_ipv4_address": "10.0.0.7",
      "virtual_ipv6_address": "fd00:f00f::b00f",
      "session_id": "gOB8vpI1MEr0vBnm",
      "api_method": "ConfigQuery",
      "bytes_sent": 0,
      "bytes_received": 0,
      "total_bytes": 0,
      "error": "LOCKOUT: user temporarily locked out due to multiple authentication failures",
      "extra": "string"
    }
  ],
  "total": 0
}

user

Endpoints for managing individual user configurations.

post__userprop_mfa_generate-secret

Body parameter

{
  "username": "niccolo@paganini.it",
  "reset_secret": true,
  "locked": true
}

Responses

Status	Meaning	Description	Schema
200	OK	Operation successfully finished.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason
404	Not Found	user not found	None

RequestJavaScript

const inputBody = '{
  "username": "niccolo@paganini.it",
  "reset_secret": true,
  "locked": true
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/mfa/generate-secret',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "totp_secret": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» username	body	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.
» reset_secret	body	boolean	false	When set to false, a user that already has a token, the function will not generate a new secret. If not present, reset_secret is assumed to be false.
» locked	body	boolean	false	When reset_locked is set to true, this will be set the newed locked status

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» totp_secret	string	false	none	the RFC 6238 TOTP secret to allow enrollment of the user.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

group

Endpoints for managing group configurations.

getgroupuserprops

Body parameter

{
  "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"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	groupRequestParameters	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved group information.	Inline
400	Bad Request	One or more arguments in the request are invalid.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	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	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	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	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	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	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	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	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	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	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	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	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	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]	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	groupLevelOnlyProps	false	none	Describes userprop properties that apply only at the group level and aren’t available for individual user configurations.
»»» members	[string]	false	none	list of all users that are members of this group. This property will be only be present if members of the group are enumerate_memberate is true in the groupRequestParameters
»»» member_count	integer	false	none	the number of users that belong to this group.
»»» subnets	[IPsubNet]	false	none	The subnets assigned to this group. This list will be a mixed list of IPv4 and IPv6 subnets. The backend userprops are group_subnets and group_subnets6
»»» dynamic_ranges	[groupIpRange]	false	none	The dynamic ranges assigned to this group. This list will contain both IPv4 and IPv6 ranges. The backend userprops for this property are group_range and group_range6.
»»»» 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.

and

Name	Type	Required	Restrictions	Description
»» anonymous	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.<win
»»» cli_script_connect_win_user_connect	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	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	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	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	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	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	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	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	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	false	none	This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source.

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "total": 0,
  "profiles": [
    {
      "name": "string",
      "deny": {},
      "deny_web": {},
      "admin": {},
      "autologin": {},
      "auth_method": {},
      "cc_commands": {},
      "totp": {},
      "password_strength": {},
      "allow_password_change": {},
      "reroute_gw": {},
      "allow_generate_profiles": {},
      "bypass_subnets": [],
      "members": [],
      "member_count": 0,
      "subnets": [],
      "dynamic_ranges": [],
      "cli_script_connect_win_user_connect": {},
      "cli_script_connect_win_user_disconnect": {},
      "cli_script_connect_win_admin_connect": {},
      "cli_script_connect_win_admin_disconnect": {},
      "cli_script_connect_mac_user_connect": {},
      "cli_script_connect_mac_user_disconnect": {},
      "cli_script_connect_mac_admin_connect": {},
      "cli_script_connect_mac_admin_disconnect": {},
      "cli_script_connect_win_env": {},
      "cli_script_connect_mac_env": {}
    }
  ]
}

misc

APIs that do not fit in any other category

get_server_config

Responses

Status	Meaning	Description	Schema
200	OK	The global server configuration was retrieved successfully.	serverConfig

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/config',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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"
}

getCWSconfig

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	WebsiteConfig

This operation does not require authentication

RequestJavaScript

const headers = {
  'Accept':'application/json'
};

fetch('/api/ui/config',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "header_image": "string",
  "hide_footer": "string",
  "enabled_auth_methods": [
    "saml",
    "userandpassword"
  ],
  "login_text": "Enter your TOTP Authentication code."
}

acme

API calls that are related to the ACME client service that requests certificates from ACME enabled providers.

post__acme_set-acme-challenge

Body parameter

{
  "expiry": 0,
  "tls_alpn_challenges": [
    {
      "servername": "string",
      "certificate": "string",
      "private_key": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
400	Bad Request	Something went wrong	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "expiry": 0,
  "tls_alpn_challenges": [
    {
      "servername": "string",
      "certificate": "string",
      "private_key": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/acme/set-acme-challenge',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	AcmeChallenge	false	none
» expiry	body	integer	false	A timeout in seconds after which the web server should no longer serve the challenge certificates
» tls_alpn_challenges	body	[AcmeTLSAlpnChallenge]	true	A list of tls-alpn-01 challenge certificates
»» servername	body	string	true	the servername (used in SNI) that this certificate should be presented for
»» certificate	body	pemEncodedCertificate(pem)	true	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.
»» private_key	body	pemEncodedPrivateKey(pem)	true	A private key in PEM format. This representation typically begins with `-----BEGIN PRIVATE KEY-----`, contains base64-encoded data, and ends with `-----END PRIVATE KEY-----`.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

get__acme_directory

Responses

Status	Meaning	Description	Schema
200	OK	Consolidated status overview data.	Inline
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/acme/directory',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{}

Parameters

Name	In	Type	Required	Description
url	query	string	false	The URL of an ACME CA service to query the directory for.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

The contents of the ACME directory. Refer to RFC 8555 for a description of the format of the directory. (https://datatracker.ietf.org/doc/rfc8555/)

Name	Type	Required	Restrictions	Description

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

post__acme_register-account

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully registered account.	None
401	Unauthorized	Failed to register an account with the ACME service.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/acme/register-account',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

post__acme_request-certificate

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully requested certificate.	None
401	Unauthorized	Error occurred during the request of the certificate.	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/acme/request-certificate',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

post__acme_revoke-certificate

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully revoked the current certificate.	None
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/acme/revoke-certificate',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

maintainance

post__server_failover-test

Body parameter

{
  "failover.mode": "ucarp",
  "ucarp.addr": "192.168.188.254",
  "ucarp.secret": "sharedsecret",
  "dbpush.hosts.0.enable": "true",
  "dbpush.hosts.0.public": "grace.hopper",
  "dbpush.hosts.0.internal": "PRIMARY",
  "dbpush.hosts.0.username": "root",
  "dbpush.hosts.1.enable": "true",
  "dbpush.hosts.1.public": "ada.lovelace",
  "dbpush.hosts.1.internal": "SECONDARY",
  "dbpush.hosts.1.username": "root",
  "dbpush.hosts.1.password": "",
  "dbpush.hosts.1.ssh_port": "22"
}

Responses

Status	Meaning	Description	Schema
200	OK	Results of the failoover test.	failOverTestStatus
400	Bad Request	Failover test initialisation failed.	errorReasonDetail
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "failover.mode": "ucarp",
  "ucarp.addr": "192.168.188.254",
  "ucarp.secret": "sharedsecret",
  "dbpush.hosts.0.enable": "true",
  "dbpush.hosts.0.public": "grace.hopper",
  "dbpush.hosts.0.internal": "PRIMARY",
  "dbpush.hosts.0.username": "root",
  "dbpush.hosts.1.enable": "true",
  "dbpush.hosts.1.public": "ada.lovelace",
  "dbpush.hosts.1.internal": "SECONDARY",
  "dbpush.hosts.1.username": "root",
  "dbpush.hosts.1.password": "",
  "dbpush.hosts.1.ssh_port": "22"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/failover-test',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» additionalProperties	body	string	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__server_failover-init

Body parameter

{
  "new_config": {
    "failover.mode": "ucarp",
    "ucarp.addr": "192.168.188.254",
    "ucarp.secret": "sharedsecret",
    "dbpush.hosts.0.enable": "true",
    "dbpush.hosts.0.public": "grace.hopper",
    "dbpush.hosts.0.internal": "PRIMARY",
    "dbpush.hosts.0.username": "root",
    "dbpush.hosts.1.enable": "true",
    "dbpush.hosts.1.public": "ada.lovelace",
    "dbpush.hosts.1.internal": "SECONDARY",
    "dbpush.hosts.1.username": "root",
    "dbpush.hosts.1.password": "",
    "dbpush.hosts.1.ssh_port": "22"
  },
  "old_config": {
    "property1": "string",
    "property2": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Secondary node setup was successful.	None
400	Bad Request	Something went wrong during secondary node setup	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "new_config": {
    "failover.mode": "ucarp",
    "ucarp.addr": "192.168.188.254",
    "ucarp.secret": "sharedsecret",
    "dbpush.hosts.0.enable": "true",
    "dbpush.hosts.0.public": "grace.hopper",
    "dbpush.hosts.0.internal": "PRIMARY",
    "dbpush.hosts.0.username": "root",
    "dbpush.hosts.1.enable": "true",
    "dbpush.hosts.1.public": "ada.lovelace",
    "dbpush.hosts.1.internal": "SECONDARY",
    "dbpush.hosts.1.username": "root",
    "dbpush.hosts.1.password": "",
    "dbpush.hosts.1.ssh_port": "22"
  },
  "old_config": {
    "property1": "string",
    "property2": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/failover-init',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
» new_config	body	object	false	the values of the configuration keys to use for the new configuration The format of the keys is the same as for the /config-items/{configurationProfile}/ post API and the fail over test needs the keys `dbpush.`, `ucarp.`, and `failover.mode`
»» additionalProperties	body	string	false	none
» old_config	body	object	false	The old configuration. This be needed as the old failover node might be different from new failover node. Format is the same as new_config
»» additionalProperties	body	string	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Default

notificationCreate

Body parameter

{
  "notification_type": "CLUSTER_RESTART_PENDING"
}

Parameters

Name	In	Type	Required	Description
body	body	notificationMessage	false	none
» notification_type	body	string	true	the type of notification

Enumerated Values

Parameter	Value
» notification_type	CLUSTER_RESTART_PENDING
» notification_type	NODE_RESTARTED

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	None
400	Bad Request	notification creation failed	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "notification_type": "CLUSTER_RESTART_PENDING"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/notification/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

clusterset

Body parameter

{
  "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	false	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	body	certificateFingerprint(sha256)	false	The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Properties on the cluster node have been successfully set.	None
400	Bad Request	Error setting the cluster properties failed	errorReason
403	Forbidden	Only admin users are allowed to use this API endpoint.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "invalidchars": {
    "value": {
      "message": "api_endpoint has invalid characters in it"
    }
  }
}

Schemas

WebsiteConfig

Website appearance and configuration details that must be available without authentication.

Properties

Name	Type	Required	Restrictions	Description
header_image	string,null	false	none	An URI to an alternative header image that is customised. If not present use default logo
hide_footer	string,null	false	none	If true then hide footer
enabled_auth_methods	[string]	true	none	A list of enabled authentication methods. UI should only offer enabled methods. These are NOT the backend methods but rather the ways of providing credentials regardless of the backend authentication method. The userandpasswordwithmfa method will provide the user with username, password and TOTP field for the login to make allow entering both factors in one step instead of two.
login_text	string,null	false	none	Alternative login text.

json

{
  "header_image": "string",
  "hide_footer": "string",
  "enabled_auth_methods": [
    "saml",
    "userandpassword"
  ],
  "login_text": "Enter your TOTP Authentication code."
}

profileType

Specifies the connection profile type.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Specifies the connection profile type.

Enumerated Values

Property	Value
anonymous	autologin
anonymous	userlogin
anonymous	generic
anonymous	epki-generic

json

"autologin"

username

A case-sensitive username. If this differs from the one associated with the auth token, admin privileges may be required for certain operations.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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.

json

"niccolo@paganini.it"

groupname

Name of a user group used in user management. specify a group name.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Name of a user group used in user management. specify a group name.

json

"string"

installerType

Specifies the type of the installer binary to be generated.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Specifies the type of the installer binary to be generated.

Enumerated Values

Property	Value
anonymous	win_v3
anonymous	mac_v3
anonymous	win
anonymous	mac
anonymous	ios
anonymous	android
anonymous	linux

json

"win_v3"

certProfileSorting

Defines the attribute used to sort certificate profiles.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Defines the attribute used to sort certificate profiles.

Enumerated Values

Property	Value
anonymous	serial
anonymous	username
anonymous	not_before
anonymous	type
anonymous	not_after
anonymous	tls_crypt_v2
anonymous	last_used
anonymous	algorithm

json

"serial"

userSorting

Defines the attribute used to sort user profiles.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Defines the attribute used to sort user profiles.

Enumerated Values

Property	Value
anonymous	admin
anonymous	name
anonymous	autologin
anonymous	group
anonymous	mfa_status

json

"admin"

groupSorting

Defines the attribute used to sort groups.

Properties

None

json

"name"

logDBSortingFields

Enum of valid sorting fields for querying the log database.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Enum of valid sorting fields for querying the log database.

Enumerated Values

Property	Value
anonymous	node
anonymous	username
anonymous	service
anonymous	duration
anonymous	active
anonymous	virtual_ipv4_address
anonymous	bytes_received
anonymous	bytes_sent
anonymous	timestamp
anonymous	error
anonymous	version
anonymous	gui_version
anonymous	platform
anonymous	protocol

json

"node"

sortingDirection

The direction in which to sort results (e.g., ascending or descending).

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The direction in which to sort results (e.g., ascending or descending).

Enumerated Values

Property	Value
anonymous	asc
anonymous	desc

json

"asc"

UserCertProfile

A certificate profile of a user.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

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	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

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",
  "device_id": "string",
  "comment": "My toaster running Doom",
  "profile_type": "autologin",
  "tls_crypt_v2": true,
  "last_used": "2019-08-24",
  "username": "string"
}

usertype

Indicates whether the user is an admin.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Indicates whether the user is an admin.

Enumerated Values

Property	Value
anonymous	admin
anonymous	user

json

"admin"

userproperties

Properties assigned to a user.

Properties

Name	Type	Required	Restrictions	Description
requires_mfa_enrollment	boolean	true	none	if present, this user needs to finish MFA enrollment
user_type	usertype	false	none	Indicates whether the user is an admin.
mfa_secret	string	false	none	This is an optional field that is only visible if the user has not enrolled yet or is an admin user.
allowed_profiles	[profileType]	false	none	A list of profiles types allowed for the user. Sorted by preference.
enforce_strong_passwords	boolean	false	none	If true, than checking for strong password is required.
allow_password_change	boolean	false	none	Indicates whether password change is allowed for the user.

json

{
  "requires_mfa_enrollment": true,
  "user_type": "admin",
  "mfa_secret": "string",
  "allowed_profiles": [
    "autologin"
  ],
  "enforce_strong_passwords": true,
  "allow_password_change": true
}

MFAChallenge

Properties

Name	Type	Required	Restrictions	Description
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.

json

{
  "challenge": "If you could be any animal, what would you be and why?",
  "echo": true,
  "challenge_context": "812jh3a8s"
}

MFAChallengeResponse

Properties

Name	Type	Required	Restrictions	Description
response	string(password)	false	none	the user’s response to the MFA challenge
challenge_context	string	false	none	The challenge context that was in the MFAChallenge.
username	string	true	none	The user name for login

json

{
  "response": "pa$$word",
  "challenge_context": "FJAIIXMAIOFLGAK23",
  "username": "string"
}

MFAResponse

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	loginParameters	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	MFAChallengeResponse	false	none	none

json

{
  "request_admin": true,
  "response": "pa$$word",
  "challenge_context": "FJAIIXMAIOFLGAK23",
  "username": "string"
}

certificateSerial

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(int64)	false	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.

json

"1708464983752887'"

certificateCommonName

The certificate common name (CN).

Properties

Name	Type	Required	Restrictions	Description
anonymous	string,null	false	none	The certificate common name (CN).

json

"OpenVPN VPN server CA"

loginParameters

Properties

Name	Type	Required	Restrictions	Description
request_admin	boolean	false	none	Whether this login should request admin privileges. Without this set to true, even admin users will not be granted admin privileges after login.

json

{
  "request_admin": true
}

userAndPw

Properties

Name	Type	Required	Restrictions	Description
username	string	true	none	The user name for login. Note that if this is case-sensitive or not depends on the OpenVPN Access Server configuration.
password	string	true	none	The password for login in clear text
totp	string	false	none	Optional TOTP token for the user when wishing to do all MFA credentials in one go.

json

{
  "username": "string",
  "password": "string",
  "totp": "string"
}

samlLoginAssertion

Properties

Name	Type	Required	Restrictions	Description
assertion	string(xml)	true	none	SAML Assertion in xml format , encoded as base64-string
relay_state	string	false	none	Optional relay state identifying the type of SAML request. If not passed or empty, defaults to cws

json

{
  "assertion": "string",
  "relay_state": "vpnauth~nod1~Dfk3287761d"
}

userAndPwLogin

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	loginParameters	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	userAndPw	false	none	none

json

{
  "request_admin": true,
  "username": "string",
  "password": "string",
  "totp": "string"
}

samlLogin

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	loginParameters	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	samlLoginAssertion	false	none	none

json

{
  "request_admin": true,
  "assertion": "string",
  "relay_state": "vpnauth~nod1~Dfk3287761d"
}

loginResponse

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» user_properties	userproperties	false	none	Properties assigned to a user.
» username	string	true	none	username of the authenticated user

and

Name	Type	Required	Restrictions	Description
anonymous	authTokenResponse	false	none	none

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"
}

authTokenResponse

Properties

Name	Type	Required	Restrictions	Description
auth_token	string	true	none	An opaque token that is used to access protected APIs
expires_after	string(%a %b %d %Y %-H:%-M:%-S GMT%z (%Z))	true	none	date in UTC when token expires
renewable_until	string(%a %b %d %Y %-H:%-M:%-S GMT%z (%Z))	true	none	date in UTC when the token is no longer renewable

json

{
  "auth_token": "string",
  "expires_after": "string",
  "renewable_until": "string"
}

profileDeleteCode

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	none

Enumerated Values

Property	Value
anonymous	{“204”:null,“description”:“profile successfully deleted”}
anonymous	{“404”:null,“description”:“profile to be deleted was not found”}
anonymous	{“403”:null,“description”:“profile to be deleted is not owned by the user or another error”}

json

{
  "204": null,
  "description": "profile successfully deleted"
}

clientReason

Message given to the client explaining why it was disconnected.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Message given to the client explaining why it was disconnected.

json

"Client disconnected for administrative reasons"

adminReason

Message logged for administrators explaining why a client was disconnected.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Message logged for administrators explaining why a client was disconnected.

json

"John should not be working after hours"

vpnConnectionID

Properties

Name	Type	Required	Restrictions	Description
daemon_id	daemonID	true	none	An ID that identifies the specific OpenVPN daemon the client is connected to.
client_id	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.

json

{
  "daemon_id": "openvpn_7",
  "client_id": 7
}

errorReason

Properties

Name	Type	Required	Restrictions	Description
reason	string	true	none	a user-friendly message of reason of API failure, allowed to be displayed
title	string	false	none	a title describing the error message

json

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

errorReasonDetail

A set of field-specific error messages. Each key in the response corresponds to the input field that caused the error. For example, when setting configuration keys, the keys in this object match the configuration fields that failed validation.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	errorReason	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» detail	object	false	none	errorReasons that specify the errorReason for a specific sub object
»» additionalProperties	errorReason	false	none	none

json

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

configurationProfile

The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The configuration profile name. The default profile is typically DEFAULT. Additional profiles allow for staging changes or creating backups.

json

"string"

certificateAlgorithm

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).

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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).

json

"rsa2048"

certificateType

The type of certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The type of certificate.

Enumerated Values

Property	Value
anonymous	ca
anonymous	old_ca
anonymous	cross_ca
anonymous	client

json

"ca"

certificateDetails

Properties

Name	Type	Required	Restrictions	Description
serial	certificateSerial	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	true	none	The certificate common name (CN).
algorithm	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.

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"
}

certificateInformationDetails

Provides more information about a certificate.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» sha256fp	certificateFingerprint	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

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
}

certificateAuthorityDetails

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» cert_type	certificateType	true	none	The type of certificate.
» client_profiles	integer	true	none	the number of VPN client profiles are issued by this CA.

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
}

certificateCreateRequest

Request body to create a certificate. If a CA and its key are provided, the certificate is signed by the CA; otherwise, it is self-signed.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateRequest	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» cert_template	string	true	none	the template to use when creating the certificate. This mainly controls the key usage (KU) and extend key usage (EKU) attributes of the certificate
» days_to_expiry	integer	false	none	number of days while certificate is considered valid
» private_key_passphrase	string	false	none	passhprase for the certificate’s private key
» signing_ca	pemEncodedCertificate	false	none	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.
» subj_alt_dns_names	[string]	false	none	a list of DNS names that should be added as SubjectAlternativeName DNSJake in the certificate if the cert_template is webserver.
» signing_ca_key	pemEncodedPrivateKey	false	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-----`.
» signing_ca_config_key	any	false	none	the name of a configuration key (e.g. cs.priv.key) that will be used to check the certificate validity
» signing_ca_private_key_passphrase	string	false	none	passhprase for signing CA’s private key

Enumerated Values

Property	Value
cert_template	spcert
cert_template	ca
cert_template	intermediate_ca
cert_template	webserver
cert_template	server
cert_template	client
cert_template	hybrid

json

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}

certificateRequest

Properties

Name	Type	Required	Restrictions	Description
algorithm	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).
common_name	certificateCommonName	false	none	The certificate common name (CN).

json

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA"
}

integerConfigurationLimits

Properties

Name	Type	Required	Restrictions	Description
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

json

{
  "default_value": 0,
  "max_value": 0,
  "min_value": 0
}

integerConfigurationValue

A server configuration setting expressed as an integer.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» value	integer	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	integerConfigurationLimits	false	none	none

json

{
  "value": 0,
  "default_value": 0,
  "max_value": 0,
  "min_value": 0
}

invalidIntegerConfigurationValue

A configuration value that is expressed as an integer.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	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.

json

{
  "default_value": 0,
  "max_value": 0,
  "min_value": 0,
  "value": "string",
  "invalid_value": true
}

stringConfigurationValue

A server configuration setting expressed as a string. Only one of value or redacted_value will be present.

Properties

Name	Type	Required	Restrictions	Description
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

Enumerated Values

Property	Value
type_hint	ipv4Address
type_hint	ipv6Address
type_hint	ipAddress
type_hint	hostname
type_hint	pemCertificate
type_hint	pemPrivateKey

json

{
  "value": "string",
  "redacted_value": "PEM encoded private key [rsa2048]",
  "default_value": "string",
  "allowed_values": [
    "string"
  ],
  "type_hint": "ipv4Address"
}

booleanConfigurationValue

Properties

Name	Type	Required	Restrictions	Description
value	boolean	false	none	none
default_value	boolean	false	none	The default value for the configuration.

json

{
  "value": true,
  "default_value": true
}

customConfigurationValue

A configuration key unknown to the backend, possible user-defined or carried over from a new version during downgrade.

Properties

Name	Type	Required	Restrictions	Description
value	string	false	none	none

json

{
  "value": "string"
}

configurationValueSource

Indicates the source from which the current value was derived, such as default or user-set.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Indicates the source from which the current value was derived, such as default or user-set.

Enumerated Values

Property	Value
anonymous	default
anonymous	local_db
anonymous	cluster_db
anonymous	mysql_standalone_db
anonymous	as_conf
anonymous	environment
anonymous	runtime
anonymous	other

json

"default"

configurationItemKey

The configuration value's key.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The configuration value's key.

json

"vpn.server.cipher"

configurationItem

Represents a single configuration item. Check the derived_from field to see whether it’s user-set, default, or inherited.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» name	configurationItemKey	true	none	The configuration value's key.
» derived_from	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	false	none	A server configuration setting expressed as an integer.

xor

Name	Type	Required	Restrictions	Description
» anonymous	invalidIntegerConfigurationValue	false	none	A configuration value that is expressed as an integer.

xor

Name	Type	Required	Restrictions	Description
» anonymous	booleanConfigurationValue	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	stringConfigurationValue	false	none	A server configuration setting expressed as a string. Only one of `value` or `redacted_value` will be present.

xor

Name	Type	Required	Restrictions	Description
» anonymous	customConfigurationValue	false	none	A configuration key unknown to the backend, possible user-defined or carried over from a new version during downgrade.

Enumerated Values

Property	Value
type	custom
type	integer
type	boolean
type	string
category	deprecated
category	removed
category	normal
category	required
category	derived
category	advanced
category	custom

json

{
  "name": "vpn.server.cipher",
  "derived_from": "default",
  "type": "custom",
  "description": "string",
  "category": "deprecated",
  "value": 0,
  "default_value": 0,
  "max_value": 0,
  "min_value": 0
}

pemEncodedCertificate

A certificate in PEM format, beginning with -----BEGIN CERTIFICATE----, followed by base64-encoded content and ending with-----END CERTIFICATE-----.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(pem)	false	none	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.

json

"string"

pemEncodedPrivateKey

A private key in PEM format. This representation typically begins with -----BEGIN PRIVATE KEY-----, contains base64-encoded data, and ends with -----END PRIVATE KEY-----.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(pem)	false	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

"string"

certificateFingerprint

The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(sha256)	false	none	The SHA256 hash of the certificate body, commonly refferred to as the fingerprint of the certificate.

json

"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"

apiEndpoint

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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.

json

"https://node1:945"

restartMode

The restart mode requested for Access Server:

warm: restarts only internal services that require restarting
cold: fully restarts Access Server
systemctl: instructs Access Server to restart itself using systemd/systemctl.
server_agent: instruct OpenVPN Access Server to initiate a full reinit of the server agent, including re-reading the configuration in as.conf.

If rereading the configuration from a new DB URI (e.g. after converting the DB or creating a cluster) the mode ‘cold’ should generally be sufficient, as it will revalidate the individual services' need to reinit, based on the information in the DB being used at that moment.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The restart mode requested for Access Server: - warm: restarts only internal services that require restarting - cold: fully restarts Access Server - systemctl: instructs Access Server to restart itself using systemd/systemctl. - server_agent: instruct OpenVPN Access Server to initiate a full reinit of the server agent, including re-reading the configuration in as.conf. If rereading the configuration from a new DB URI (e.g. after converting the DB or creating a cluster) the mode ‘cold’ should generally be sufficient, as it will revalidate the individual services' need to reinit, based on the information in the DB being used at that moment.

Enumerated Values

Property	Value
anonymous	cold
anonymous	warm
anonymous	dry_run
anonymous	systemctl
anonymous	server_agent

json

"cold"

connectedVPNClient

Represents a connected VPN client, including the current session and connection details.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	vpnConnectionID	false	none	none

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

json

{
  "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"
}

clientID

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	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.

json

daemonID

An ID that identifies the specific OpenVPN daemon the client is connected to.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	An ID that identifies the specific OpenVPN daemon the client is connected to.

json

"openvpn_7"

vpnDaemonStatus

The current status of a VPN daemon.

Properties

Name	Type	Required	Restrictions	Description
dco	boolean	false	none	if DCO is used on this daemon instance
version	string	false	none	the OpenVPN 2.x version of the daemon

json

{
  "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"
}

dcoModuleStatus

Properties

Name	Type	Required	Restrictions	Description
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

json

{
  "available": true,
  "version": "0.2.20230323"
}

logDBRecord

Properties

Name	Type	Required	Restrictions	Description
timestamp	string(date-time)	true	none	record modification timestamp
node	any	true	none	AS node that created the log report
username	any	false	none	username that created the entry
start_time	any	false	none	start time of the event or just time of the event if duration is missing
duration	integer,null	false	none	duration of the event in seconds
service	string	false	none	the service of OpenVPN Access Server that created the event
active	boolean	false	none	if the session is still active
auth	boolean	false	none	whether authentication succeeded or not
platform	any	false	none	the platform of the client.
version	any	false	none	the version of the OpenVPN component that implement the OpenVPN protocol
protocol	string	false	none	the protocol being used
gui_version	any	false	none	the IV_GUI version the client reported.
real_address	string	false	none	the IP address the client is connected from
server_port	integer	false	none	the server side port the client connects/connected to
virtual_ipv4_address	string	false	none	the virtual or VPN address of the client
virtual_ipv6_address	string	false	none	none
session_id	string	false	none	internal session ID of the connection (this might be truncated)
api_method	string	false	none	description of the API method that was called
bytes_sent	integer	false	none	number of bytes sent
bytes_received	integer	false	none	number of bytes received
total_bytes	integer	false	none	total number of transferred bytes. (This seems and probably is redundant but currently we keep this as individual record in the backend database)
error	string	false	none	error message on auth failure
extra	string	false	none	service-specific data

json

{
  "timestamp": "2019-08-24T14:15:22Z",
  "node": "vpn-12.example.com",
  "username": null,
  "start_time": null,
  "duration": 0,
  "service": "WEB_ADMIN",
  "active": true,
  "auth": true,
  "platform": "android",
  "version": "2.6.11",
  "protocol": "tcp",
  "gui_version": "de.blinkt.openvpn_0.7.48",
  "real_address": "1.2.7.8:23123",
  "server_port": 1194,
  "virtual_ipv4_address": "10.0.0.7",
  "virtual_ipv6_address": "fd00:f00f::b00f",
  "session_id": "gOB8vpI1MEr0vBnm",
  "api_method": "ConfigQuery",
  "bytes_sent": 0,
  "bytes_received": 0,
  "total_bytes": 0,
  "error": "LOCKOUT: user temporarily locked out due to multiple authentication failures",
  "extra": "string"
}

licenseInfo

Contains general fields shared across licensing models, as well as additional fields specific to the current ‘licensing_type’ in use.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» licensing_type	string	false	none	the method that Access Server is licensed
» current_cc	integer	false	none	the number of current concurrent connections
» max_cc	integer	false	none	the maximum amount of connections that this license allows to use. For license types are single node (aws, fixed, unlicensed) this is also the limit for all connections. For shared licenses (subscription) this denotes the total number of connections in the subscription and the current number of allocated connection for an Access Server is denoted in cc_limit.

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	fixedLicenseInfo	false	none	Describes the current licensing details for Access Server. Multiple fixed licenses can be assigned, and the total number of allowed connections is the sum of all valid (non-expired)licenses.

xor

Name	Type	Required	Restrictions	Description
» anonymous	subscriptionInfo	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	unlicensedInfo	false	none	Placeholder information returned when Access Server is not currently licensed.

xor

Name	Type	Required	Restrictions	Description
» anonymous	awsTieredLicenseInfo	false	none	none

Enumerated Values

Property	Value
licensing_type	unlicensed
licensing_type	subscription
licensing_type	awstiered
licensing_type	fixed

json

{
  "licensing_type": "unlicensed",
  "current_cc": 3,
  "max_cc": 13,
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

unlicensedInfo

Placeholder information returned when Access Server is not currently licensed.

Properties

None

json

{}

fixedLicenseInfo

Describes the current licensing details for Access Server. Multiple fixed licenses can be assigned, and the total number of allowed connections is the sum of all valid (non-expired)licenses.

Properties

Name	Type	Required	Restrictions	Description
fixed_licenses	[object]	false	none	none
» expiry	string(date-time)	false	none	expiry date of the license.
» key	string	false	none	the key of the fixed license
» max_cc	integer	false	none	maximum amount of connection for this fixed license.

json

{
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

awsTieredLicenseInfo

Properties

Name	Type	Required	Restrictions	Description
region	string	false	none	the AWS region
product_code	string	false	none	the AWS product code that identifies this license
instance_id	string	false	none	the AWS instance ID

json

{
  "region": "eu-central-1",
  "product_code": "3ihdqli79gl9v2jnlzs6nq60h",
  "instance_id": "i-0c1ac1ca2f4b4a23b"
}

subscriptionInfo

Properties

Name	Type	Required	Restrictions	Description
agent_id’	string	false	none	the identifier the client uses to connect to STS
agent_disabled	boolean	false	none	none
cc_limit	integer	false	none	the limit of connection assigned to the Access Server. This can dynamically change.
error	string,null	false	none	if an error occurred this will be set to a human-readable error message
fallback_cc’	integer	false	none	the amount of connection that the subscription will revert to if the subscription server cannot be reached for an extended time (grace_period)
grace_period	integer	false	none	number of days after which the subscription will revert to fallback_cc amount of connections
last_successful_update	string(date-time)	false	none	the last time the subscription was successfully updated
total_cc	integer	false	none	the total number of current connections for the subscription over all Access Server that use this subscription. Basically the current_cc of all OpenVPN Access Server using this subscription summed up.
name	string	false	none	A name given to the subscription.
subkey	string	false	none	The subkey that uniquely identifies the subscription on the backend.
billing_id	string	false	none	An opaque identifier that allows identifying the subscription on the billing portal.
next_update	string(date-time)	false	none	when the next update to the subscription server is scheduled
updates_failed	integer	false	none	the number of updates that failed since the last successful update.
notes	[string]	false	none	both server generated and locally generated additional notes to display to the user
overdraft	boolean	false	none	Subscription is currently in overdraft mode
server	string	false	none	the server that is used to for subscription tracking
type	string	false	none	Type of the subscription as reported by the STS server
state	string	false	none	the current state of the subscription agent
props	dict	false	none	if present, the additional properties that are reported to STS for Access Server Link.

Enumerated Values

Property	Value
state	SUBSCRIPTION_OK
state	SUBSCRIPTION_EXPIRED
state	NOT_CONFIGURED
state	AGENT_DISABLED
state	SUBSCRIPTION_INVALID
state	SUBSCRIPTION_ENDED
state	SUBSCRIPTION_PAUSED
state	STSTRACK_ERROR
state	REQUEST_ERROR

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
}

profileToken

A token (typically one-time use) that can be used to retrieve a connection profile from Access Server. Access Server

Properties

Name	Type	Required	Restrictions	Description
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	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

json

{
  "token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
  "username": "arne@openvpn.net",
  "expires": "2019-08-24T14:15:22Z",
  "profile_type": "autologin",
  "usages": 1,
  "comment": "connected from my iPhone"
}

userPropUser

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	userLevelOnlyProps	false	none	Describes userprop properties that are exclusive to individual users and cannot be inherited from group or global levels.

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

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
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
    }
  }
}

userPropUserSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	userLevelOnlyProps	false	none	Describes userprop properties that are exclusive to individual users and cannot be inherited from group or global levels.

and

Name	Type	Required	Restrictions	Description
anonymous	userPropScriptsSet	false	none	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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}

userPropGroup

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	groupLevelOnlyProps	false	none	Describes userprop properties that apply only at the group level and aren’t available for individual user configurations.

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

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
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
    }
  }
}

userPropGroupSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	groupLevelOnlyProps	false	none	Describes userprop properties that apply only at the group level and aren’t available for individual user configurations.

and

Name	Type	Required	Restrictions	Description
anonymous	userPropScriptsSet	false	none	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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}

userPropUserDefault

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	defaultUserOnlyProps	false	none	Describes properties that are available for groups but not applicable to individual users.

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» group	string	false	none	the group a user belongs too (conn_group)

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"
}

userPropUserDefaultSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	defaultUserOnlyProps	false	none	Describes properties that are available for groups but not applicable to individual users.

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» group	string	false	none	the group a user belongs too (conn_group)

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "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"
}

defaultUserOnlyProps

Describes properties that are available for groups but not applicable to individual users.

Properties

Name	Type	Required	Restrictions	Description
def_deny	boolean	false	none	If this is set to true user accounts will not be created if they are not listed in userprop. Normally, if an external auth is used (e.g. LDAP), then a user will automatically create if the external authentication system indicates a successful login.

json

{
  "def_deny": true
}

groupLevelOnlyProps

Describes userprop properties that apply only at the group level and aren’t available for individual user configurations.

Properties

Name	Type	Required	Restrictions	Description
members	[string]	false	none	list of all users that are members of this group. This property will be only be present if members of the group are enumerate_memberate is true in the groupRequestParameters
member_count	integer	false	none	the number of users that belong to this group.
subnets	[IPsubNet]	false	none	The subnets assigned to this group. This list will be a mixed list of IPv4 and IPv6 subnets. The backend userprops are group_subnets and group_subnets6
dynamic_ranges	[groupIpRange]	false	none	The dynamic ranges assigned to this group. This list will contain both IPv4 and IPv6 ranges. The backend userprops for this property are group_range and group_range6.

json

{
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ]
}

userLevelOnlyProps

Describes userprop properties that are exclusive to individual users and cannot be inherited from group or global levels.

Properties

Name	Type	Required	Restrictions	Description
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]	false	none	The IP addresses and port-ranges that are exposed on this client.
dmz_ipv6	[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]	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.

Enumerated Values

Property	Value
mfa_status	pending
mfa_status	disabled
mfa_status	enrolled

json

{
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ]
}

userPropValue

This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source.

Properties

Name	Type	Required	Restrictions	Description
anonymous	object,null	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.

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration

json

{
  "value": "string",
  "inherited": true,
  "inherited_source_type": "default",
  "inherited_source_name": "administrators"
}

userProp

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

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	the name of the user or group.
deny	userPropValue	false	none	This object describes a single user property value. If the value is inherited, the response includes metadata about the inheritance source.
deny_web	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	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	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	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	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	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	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	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	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	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]	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.

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
    }
  ]
}

userPropSet

The same as userProp schema. With the difference that it 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
name	string	false	none	the name of the user or group.
deny	boolean	false	none	none
deny_web	boolean	false	none	none
admin	boolean	false	none	none
autologin	boolean	false	none	none
auth_method	string	false	none	none
cc_commands	string	false	none	none
totp	boolean	false	none	none
password_strength	boolean	false	none	none
allow_password_change	boolean	false	none	none
reroute_gw	boolean	false	none	none
allow_generate_profiles	boolean	false	none	none
bypass_subnets	[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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ]
}

userPropScripts

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.<win|mac|all>.<user|admin>.<connect|disconnect>
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	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	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	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	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	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	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	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	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	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	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	false	none	none
error	[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	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	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]	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	true	none	none
installers	[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	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	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	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	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	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	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	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	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	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	true	none	Specifies the type of the installer binary to be generated.
profile_type	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	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	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	false	none	Defines the attribute used to sort certificate profiles.
» filters	object	false	none	none
»» username	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» serial	filterInteger	false	none	Specifies a filter for integer-based attributes using a defined operation.
»» autologin	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	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	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	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	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	false	none	Specifies a filter for string-based attributes using a defined operation.
»» signing_ca_cn	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» anywhere	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	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	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	false	none	Specifies a filter for string-based attributes using a defined operation.
»»» group	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.

and

Name	Type	Required	Restrictions	Description
»» anonymous	commonUserGroupFilters	false	none	Filters that apply to both user and group requests.

continued

Name	Type	Required	Restrictions	Description
» users	[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	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	false	none	Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid.
autologin	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	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	true	none	Specifies the connection profile type.
username	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	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	false	none	Enum of valid sorting fields for querying the log database.
» filters	object	false	none	none
»» start_time	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	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	false	none	Specifies a filter for duration-based attributes using a defined operation.
»» node	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» username	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» active	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	false	none	Specifies a filter for boolean attributes. The operation is always equality (equal) since only true or false values are valid.
»» service	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» virtual_ipv4_address	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» bytes_sent	filterBandwidth	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» bytes_received	filterBandwidth	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» gui_version	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» version	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» platform	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» protocol	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
»» anywhere	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	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	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	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	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	false	none	Specifies a filter for string-based attributes using a defined operation.

and

Name	Type	Required	Restrictions	Description
»» anonymous	commonUserGroupFilters	false	none	Filters that apply to both user and group requests.

continued

Name	Type	Required	Restrictions	Description
» enumerate_members	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]	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	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	false	none	Specifies a filter for string-based attributes using a defined operation.
» groupname	filterString	false	none	Specifies a filter for string-based attributes using a defined operation.
» username	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]	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]	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	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	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	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	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	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	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	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	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	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	false	none	Name of a user group used in user management. specify a group name.
subnet	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

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	false	none	Describes an IP subnet.

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» service	[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	true	none	The type of the rule.
match_type	accessControlRuleTypeEnum	true	none	The match type of the rule.
match_data	string	true	none	The match data.
action	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	true	none	The type of the rule.
match_type	accessControlRuleTypeEnum	true	none	The match type of the rule.
match_data	string	true	none	The match data.
action	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	false	none	The result of a single failover test.
license_primary	failOverTestResult	false	none	The result of a single failover test.
license_secondary	failOverTestResult	false	none	The result of a single failover test.
connectivity	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	true	none	A certificate in PEM format, beginning with `-----BEGIN CERTIFICATE----`, followed by base64-encoded content and ending with`-----END CERTIFICATE-----`.
private_key	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]	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.

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

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

Body parameter

{
  "username": "string",
  "password": "string",
  "totp": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	userAndPwLogin	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	successful auth	loginResponse
401	Unauthorized	missing MFA or ask to login via SAML workflow	Inline
403	Forbidden	wrong user and/or password or user access denied	errorReason
409	Conflict	MFA enrollment is required. The intermediate auth token will be returned. This auth token should be used for enrolllment.	loginResponse

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
» MFAChallenge	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "response": "pa$$word",
  "challenge_context": "FJAIIXMAIOFLGAK23",
  "username": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	MFAResponse	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	successful auth	loginResponse
403	Forbidden	wrong authentication info	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "assertion": "string",
  "relay_state": "vpnauth~nod1~Dfk3287761d"
}

Parameters

Name	In	Type	Required	Description
body	body	samlLogin	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	successful auth	loginResponse
400	Bad Request	Wrong RelayState parameter or Invalid SAML assertion	errorReason
401	Unauthorized	Invalid authentication assertion request. Returned when status of authentication was not handled or unknown.	errorReason
403	Forbidden	User access denied or Account configuration problem or no valid SAML configuration or This profile requires web based SAML Authentication.	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Responses

Status	Meaning	Description	Schema
200	OK	successful auth	authTokenResponse
401	Unauthorized	the old token has expired and can no longer be renewed	errorReason
403	Forbidden	Token renewal is no longer allowed.	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "auth_token": "string",
  "expires_after": "string",
  "renewable_until": "string"
}

changePasswordLocalUser

Body parameter

{
  "username": "string",
  "new_password": "pa$$word"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none

Responses

Status	Meaning	Description	Schema
200	OK	Password has changed successfully	Inline
401	Unauthorized	Login failed	Inline
403	Forbidden	Forbidden. Auth token was not recent enough or security criteria of new password not met.	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

RequestJavaScript

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);
});

Responsejson

{
  "detail": "string"
}

enrollUserMFA

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully enrolled.	Inline
400	Bad Request	Provided MFA token does not match secret or other error	errorReason
403	Forbidden	only admin users are allowed to use this 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

RequestJavaScript

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);
});

Responsejson

{
  "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

Responses

Status	Meaning	Description	Schema
200	OK	Responds with installer file	string
400	Bad Request	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	“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

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
200	OK	Responds with connection profile file	string
400	Bad Request	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

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

get__GetAutologin

Responses

Status	Meaning	Description	Schema
200	OK	Responds with connection profile file	string
400	Bad Request	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

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

get__GetUserlogin

Responses

Status	Meaning	Description	Schema
200	OK	Responds with connection profile file	string
400	Bad Request	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

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

get__GetGeneric

Responses

Status	Meaning	Description	Schema
200	OK	Responds with connection profile file	string
400	Bad Request	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

RequestJavaScript

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);
});

Responsexml

<?xml version="1.0" encoding="UTF-8" ?>
<Error>
  <Type>Invalid Request</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>No permission to generate profile (9422)</Message>
</Error>

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

Body parameter

[
  "string"
]

Parameters

Name	In	Type	Required	Description
body	body	array[string]	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Responses

Status	Meaning	Description	Schema
204	No Content	token were successfully deleted	None
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	token to be deleted was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Redirect to http://server_addres/ page with saml headers in response according to OpenVPN Api spec.	None

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Redirect to http://server_addres/login?relay_state=profile	None

This operation does not require authentication

RequestJavaScript

fetch('/api/openvpn-api/profile',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

getprofilesuser

Body parameter

{
  "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	false	none

Responses

Status	Meaning	Description	Schema
200	OK	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	false	none	none
»»» serial	certificateSerial(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	true	none	The common name of the certificate.
»»» algorithm	certificateAlgorithm	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	false	none
» user	body	username	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	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	Profile was successfully generated	string
403	Forbidden	profile creation was not permitted	errorReason

Response Headers

Status	Header	Type	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

RequestJavaScript

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

Body parameter

{
  "lifetime": 0,
  "usages": 0,
  "profile_type": "autologin",
  "username": "niccolo@paganini.it"
}

Parameters

Name	In	Type	Required	Description
body	body	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 more usage requires admin privileges.
» profile_type	body	profileType	true	none
» username	body	username	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Token URL has been successfully generated	string
400	Bad Request	Token url was not generated	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	list of all still valid profile token urls	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» profileTokens	[profileToken]	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	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

RequestJavaScript

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);
});

Responsejson

{
  "profileTokens": [
    {
      "token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
      "username": "arne@openvpn.net",
      "expires": "2019-08-24T14:15:22Z",
      "profile_type": "autologin",
      "usages": 1
    }
  ]
}

deleteProfileSerial

Parameters

Name	In	Type	Required	Description
serial	path	certificateSerial	true	none

Responses

Status	Meaning	Description	Schema
200	OK	profile successfully deleted	Inline
400	Bad Request	could not delete the profile	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

RequestJavaScript

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);
});

Responsejson

{
  "message": "string"
}

deleteProfileUser

Body parameter

{
  "users": [
    "niccolo@paganini.it"
  ],
  "filter": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» users	body	[username]	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	profile successfully deleted	Inline
400	Bad Request	User profiles were not deleted	errorReason
404	Not Found	User profiles were not found	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

RequestJavaScript

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);
});

Responsejson

{
  "message": "string"
}

deleteProfile

Body parameter

[
  "1708464983752887'"
]

Parameters

Name	In	Type	Required	Description
body	body	certificateSerial	false	none

Responses

Status	Meaning	Description	Schema
200	OK	Successfully executed. Status for each profile is in the response.	Inline
400	Bad Request	could not delete the profile	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this 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	false	none	none
»» serial	certificateSerial(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	true	none	The common name of the certificate.
»» algorithm	certificateAlgorithm	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	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

RequestJavaScript

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);
});

Responsejson

[
  {
    "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

Body parameter

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA"
}

Parameters

Name	In	Type	Required	Description
body	body	certificateRequest	false	none
» algorithm	body	certificateAlgorithm	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	false	The common name of the certificate.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	New CA has been successfully created	None
400	Bad Request	the selected algorithm is not allowed or the common is too long or contains invalid characters or already exists	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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}

Responses

Status	Meaning	Description	Schema
200	OK	CA has been successfully deleted	None
400	Bad Request	the CA has still client certificates or is the only CA	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	The CA to be deleted is not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
serial	path	certificateSerial	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.

{
  "message": "Insufficient privileges to use this API"
}

CaSupportedAlgorithms

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[certificateAlgorithm]	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

RequestJavaScript

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);
});

Responsejson

[
  "rsa2048",
  "rsa3072",
  "rsa4096",
  "ed448",
  "brainpoolP384r1",
  "brainpoolP512r1",
  "secp2256k1",
  "Ed25519"
]

info

endpoints that allow to query various aspects of the running server and its status

certificateInfo

Body parameter

{
  "certificate": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» certificate	body	pemEncodedCertificate(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	information about the X509 certificate	certificateInformationDetails
400	Bad Request	the provided certificate could not be parsed or other problems.	errorReason
403	Forbidden	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Can parse both private key and certificate. The content will signal if the private key belongs to the certificate.	Inline
400	Bad Request	there was some error parsing the certificate or key	errorReason
403	Forbidden	only admin users are allowed to use this 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

RequestJavaScript

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);
});

Responsejson

{
  "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

{
  "certificate": "string",
  "chain": "string",
  "ca_roots": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	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	The certificate failed verification. Details are provided in the errorReason.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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(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(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]	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.

{
  "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	false	none	none
»»» serial	certificateSerial(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	true	none	The common name of the certificate.
»»» algorithm	certificateAlgorithm	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(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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Provides the current EULA and the status of the user accepting it.	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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

Parameters

Name	In	Type	Required	Description
no_loopback	query	boolean	false	optionally for excluding localhost

Responses

Status	Meaning	Description	Schema
200	OK	A list of Ethernet interfaces and assigned IP/IPv6 addresses	Inline
403	Forbidden	User does not have admin permission	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[serverInterface]	false	none	[describes a Linux network interface and the associated primary networks]
» name	any	false	none	the name identifying the interface
» networks	[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

RequestJavaScript

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);
});

Responsejson

[
  {
    "name": "eth0",
    "networks": [
      {},
      {},
      {}
    ]
  }
]

get__server_info

Responses

Status	Meaning	Description	Schema
200	OK	Information about the running Access Server instance	serverInfo
403	Forbidden	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

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	DCO Module status	dcoModuleStatus
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "available": true,
  "version": "0.2.20230323"
}

post__helper_status-overview

Body parameter

{
  "names": [
    "vpn.server.cipher"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
400	Bad Request	Something went wrong	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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]	false	list of configuration items that should be retrieve from the active configuration

standard response when there insufficient rights to use an API.

{
  "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	true	none	the configuration value’s key.
»»»» derived_from	configurationValueSource	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	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	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	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	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	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	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	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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	the current status of the access Server licensing	licenseInfo
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "licensing_type": "unlicensed",
  "current_cc": 3,
  "max_cc": 13,
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

checkSubscription

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	The result of the subscription test	subscriptionInfo
400	Bad Request	format the license is not detected or other error with license.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription has been successfully loaded.	None
400	Bad Request	format the license is not detected or other error with license.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

deactivateSubscription

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription has been successfully deactivated.	None
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "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.

{
  "message": "License not found on server"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Online license has been successfully activated.	None
400	Bad Request	format the license is not detected or other error with license.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

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.

{
  "message": "Fixed license already expired"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Fix license has been successfully activated.	None
400	Bad Request	format the license is not detected or other error with license.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	machine id file is returned	string
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsetext

"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	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
504	Gateway Time-out	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

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	Inline
403	Forbidden	only admin users are allowed to use this 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	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	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(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

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	None
400	Bad Request	Setting the cluster properties failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

clustergetprops

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	Inline
403	Forbidden	only admin users are allowed to use this 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	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

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "rr_dns_hostname": "cluster.example.com",
  "rr_dns_new_nodes": true
}

Parameters

Name	In	Type	Required	Description
body	body	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

{
  "message": "rr_dns_hostname has invalid characters in it"
}

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Properties on the cluster node have been successfully set.	None
400	Bad Request	Setting the cluster properties failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "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	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(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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Properties on the cluster node have been successfully set.	None
400	Bad Request	Error setting the cluster properties failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "invalidchars": {
    "value": {
      "message": "api_endpoint has invalid characters in it"
    }
  }
}

post__cluster_join

Body parameter

{
  "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	Successful operation	None
400	Bad Request	joining the cluster failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeJoinRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__cluster_create

Body parameter

{
  "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	Successful operation	None
400	Bad Request	creating the cluster failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeCreateRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__cluster_leave

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation. Leaving the cluster succeeded	None
400	Bad Request	leaving the cluster failed	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

put__database_convert

Body parameter

{
  "mysqluri": "mysql://user:password@mysql.example.com:3306/"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	None
400	Bad Request	Converting the database failed.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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	false	the URI of the mysql server.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

maintenance

APIs used for server maintenance like restarting.

get__support_report

Responses

Status	Meaning	Description	Schema
200	OK	The report that is also generated by ‘sacli support’	string
403	Forbidden	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

RequestJavaScript

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);
});

Responsetext

"string"

post__server_restart

Responses

Status	Meaning	Description	Schema
200	OK	Server restart successfully scheduled	None
400	Bad Request	Server has some misconfiguration and restart is not scheduled	errorReasonDetail
403	Forbidden	User does not have admin permission	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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	false	none

Enumerated Values

Parameter	Value
restartMode	cold
restartMode	warm
restartMode	dry_run
restartMode	systemctl
restartMode	server_agent

serverStatus

Responses

Status	Meaning	Description	Schema
200	OK	the server status	serverStatus
403	Forbidden	User does not have admin permission	None

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» active_profile	configurationProfile	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]	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

RequestJavaScript

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);
});

Responsejson

{
  "active_profile": "default",
  "profiles": [
    "default",
    "heaven",
    "hades",
    "olymp"
  ]
}

configurationProfileDelete

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
204	No Content	configuration profile successfully deleted	None
400	Bad Request	profile deletion would violate some constraints like deleting the active profile	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	configuration profile to be deleted was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

configurationProfileCreate

Body parameter

{
  "profile": "string",
  "copy_from": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» profile	body	configurationProfile	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	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	configuration profile successfully created	None
400	Bad Request	profile creation has some problem like using an invalid profile name	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	configuration profile to be copied from was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

validateConfigProfile

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success. No errors in the profile are detected	None
400	Bad Request	validation of the profile encountered some problems see the error reason for more details.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	configuration profile to be validated was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

RunSetActiveProfile

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none
restartMode	query	restartMode	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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success. No errors in the profile are detected and the new profile is being set.	None
400	Bad Request	validation of the profile encountered some problems or some other error occurred. See error reason for more details.	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	the requested configuration profile was not found.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

Body parameter

{
  "names": [
    "vpn.server.cipher"
  ]
}

Parameters

Name	In	Type	Required	Description
configurationProfile	path	configurationProfile	true	none
body	body	any	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	configuration profile to be listed was not found	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	[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	true	none	the configuration value’s key.
»»» derived_from	configurationValueSource	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	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	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	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	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

RequestJavaScript

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);
});

Responsejson

{
  "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}

Body parameter

{
  "property1": "string",
  "property2": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Configuration items were successfully updated/set	None
400	Bad Request	Configuration value do not have the correct type or another problems occurred. See errorReason for detailed information	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	configuration profile to be changed was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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	true	none
body	body	object	true	none
» additionalProperties	body	string	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

saml

API endpoints that are related to SAML based authentication

post__saml_acs

Body parameter

RelayState: string
SAMLResponse: string

Responses

Status	Meaning	Description	Schema
200	OK	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	Throw validation error if wrong request passed	None
405	Method Not Allowed	Only POST for this url is allowed. Throw unsupported error if method is not POST	None

RequestJavaScript

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 vpnauth_nodeidsessionid
» 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.

"< <head> <javascript> SAMLResponse = \"[samlassertion data]\"; RelayState = \"cwslogin\"; </javascript> [content of index.html]"

Throw validation error if wrong request passed

"< <head>HEAD content</head> <body><h1>SAML authentication failed</h1><p>assertion request is invalid</p></body>"

Only POST for this url is allowed. Throw unsupported error if method is not POST

"< <head>HEAD content</head> <body><h1>SAML authentication failed</h1><p>assertion method is not supported</p></body>"

Response Schema

This operation does not require authentication

get__saml_metadata

SAML is not configured or invalid configuration

"< <head>HEAD content</head> <body><h1>404 Not Found</h1><p>SAML not configured or invalid configuration</p></body>"

Responses

Status	Meaning	Description	Schema
200	OK	This will return xml file with metadata of the Service Provider	string
404	Not Found	SAML is not configured or invalid configuration	None

RequestJavaScript

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

Responses

Status	Meaning	Description	Schema
302	Found	Responds with redirect to Identity Provider url	None
403	Forbidden	Errors can be: Wrong RelayState parameter or assertion request is invalid	None

This operation does not require authentication

RequestJavaScript

fetch('/api/saml/redirect',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

get__auth_get-idp-url

Responses

Status	Meaning	Description	Schema
200	OK	Identity Provider URL to redirect to	string
400	Bad Request	Errors can be: Wrong RelayState parameter or SAML configuration error	errorReason

This operation does not require authentication

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	Assertion Success	None
400	Bad Request	Invalid SAML assertion in the case if empty string was passed as saml assertion	errorReason
401	Unauthorized	Wrong Relay State or other assertion error	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

get__vpn_status

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Vpn Server status	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

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);
});

Responsejson

{
  "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	false	none	none
»»» daemon_id	daemonID	true	none	an ID that identifies the OpenVPN daemon that the client is connected to
»»» client_id	clientID	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	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

Body parameter

{
  "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.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	client has been successfully disconnected	None
400	Bad Request	One or more of the clients failed to disconnect	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	A client with the specified daemon and client id could not be found.	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "user": "niccolo@paganini.it",
  "installer_type": "win_v3",
  "profile_type": "autologin",
  "tls_crypt_v2": true
}

Parameters

Name	In	Type	Required	Description
body	body	installerProfileRequest	false	none
» user	body	username	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	true	Type of the installer binary that should be created for installation.
» profile_type	body	profileType	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	Installer URL was successfully generated	string
400	Bad Request	“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

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	userPropUserDefault
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

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);
});

Responsejson

{
  "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

Body parameter

{
  "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	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this 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	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	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	false	none	This object describes a single user property value. If it is
»»» admin	userPropValue	false	none	This object describes a single user property value. If it is
»»» autologin	userPropValue	false	none	This object describes a single user property value. If it is
»»» auth_method	userPropValue	false	none	This object describes a single user property value. If it is
»»» cc_commands	userPropValue	false	none	This object describes a single user property value. If it is
»»» totp	userPropValue	false	none	This object describes a single user property value. If it is
»»» password_strength	userPropValue	false	none	This object describes a single user property value. If it is
»»» allow_password_change	userPropValue	false	none	This object describes a single user property value. If it is
»»» reroute_gw	userPropValue	false	none	This object describes a single user property value. If it is
»»» allow_generate_profiles	userPropValue	false	none	This object describes a single user property value. If it is
»»» bypass_subnets	[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	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]	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	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]	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]	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	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.<win
»»» cli_script_connect_win_user_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_admin_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_user_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_admin_disconnect	userPropValue	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	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	false	none	This object describes a single user property value. If it is

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration
mfa_status	pending
mfa_status	disabled
mfa_status	enrolled
protocol	tcp
protocol	udp
protocol	icmp

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "total": 0,
  "profiles": [
    {
      "name": "string",
      "deny": {},
      "deny_web": {},
      "admin": {},
      "autologin": {},
      "auth_method": {},
      "cc_commands": {},
      "totp": {},
      "password_strength": {},
      "allow_password_change": {},
      "reroute_gw": {},
      "allow_generate_profiles": {},
      "bypass_subnets": [],
      "password_defined": true,
      "mfa_status": "pending",
      "totp_locked": true,
      "group": "stringsection",
      "static_ipv4": "string",
      "static_ipv6": "string",
      "dmz_ip": [],
      "dmz_ipv6": [],
      "compile": true,
      "totp_secret": "string",
      "totp_admin_only": true,
      "client_to_server_subnets": [],
      "cli_script_connect_win_user_connect": {},
      "cli_script_connect_win_user_disconnect": {},
      "cli_script_connect_win_admin_connect": {},
      "cli_script_connect_win_admin_disconnect": {},
      "cli_script_connect_mac_user_connect": {},
      "cli_script_connect_mac_user_disconnect": {},
      "cli_script_connect_mac_admin_connect": {},
      "cli_script_connect_mac_admin_disconnect": {},
      "cli_script_connect_win_env": {},
      "cli_script_connect_mac_env": {}
    }
  ]
}

createUserPropUser

Body parameter

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	userPropUserSet	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	New User has been successfully created	None
400	Bad Request	the user already exists or contains invalid characters or a group of the same name already exists or one of the specified userprop is invalid.	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

createUserPropGroup

Body parameter

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	userPropGroupSet	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
201	Created	New group has been successfully created	None
400	Bad Request	the group already exists or contains invalid characters or a user of the same name already exists or one of the properties has an invalid value.	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

listAccessLists

Body parameter

{
  "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"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	accessListRequestParameters	false	none
» order_by	body	string	false	none
» filters	body	object	false	filters for the access list objects.
»» internal_representation	body	filterString	false	This specifies that the result should be filtered by this attribute with the specified operation.
»»» value	body	string	true	none
»»» operation	body	string	true	none
»» groupname	body	filterString	false	This specifies that the result should be filtered by this attribute with the specified operation.
»» username	body	filterString	false	This specifies that the result should be filtered by this attribute with the specified operation.
»» object_type	body	string	false	Only return users or groups in the response.
» groups	body	[groupname]	false	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	body	[username]	false	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

Parameter	Value
» order_by	internal_prop_representation
» order_by	name
»»» operation	equal
»»» operation	substring
»»» operation	not_equal
»» object_type	user
»» object_type	group
»» object_type	all

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

Response Schema

Status Code 200

A list of all matching access lists

Name	Type	Required	Restrictions	Description
» profiles	[oneOf]	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. Either username or groupname is set to indicate whether this is a user or group assigned access rules. ]
»» username	username	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	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	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.
»»»» type	string	false	none	none
»»»» accept	boolean	false	none	specifies if we accept or deny this particular access
»»»» username	username	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	false	none	a group name that is being in used in user management to specify a group name.
»»»» subnet	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

allOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	object	false	none	describes an IP subnet.
»»»»»» 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	object	false	none	none
»»»»»» service	[oneOf]	false	none	[describes an IP UDP/TCP service or an icmp service]

oneOf

Name	Type	Required	Restrictions	Description
»»»»»»» anonymous	portRange	false	none	Describes a layer4 (TCP/UDP) port or port-range. protocol may only be udp or tcp
»»»»»»»» protocol	layer4protocol	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)

xor

Name	Type	Required	Restrictions	Description
»»»»»»» anonymous	icmpService	false	none	Describes an icmp service type. protocol is always icmp
»»»»»»»» protocol	layer4protocol	false	none	specifies a Layer 4 protocol (e.g. udp or tcp)
»»»»»»»» type	string	false	none	none

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	user
type	group
type	route
type	nat
type	all
type	all_vpn_clients
type	all_s2c_subnets
protocol	tcp
protocol	udp
protocol	icmp
protocol	tcp
protocol	udp
protocol	icmp
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
type	access_from_ipv6
type	access_from_ipv4
type	access_to_ipv4
type	access_to_ipv6

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/access/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

setAccessLists

Body parameter

{
  "items_set": [
    {
      "username": "johann",
      "access_route": {}
    },
    {
      "username": "wolfgang",
      "access_route": null,
      "type": "access_to_ipv4"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» items_set	body	array	false	none
»» username	body	username	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
»» groupname	body	groupname	false	a group name that is being in used in user management to specify a group name.
»» access_route	body	any	false	none
»»» anonymous	body	accessRoute	false	Format of OpenVPN Access Server’s access lists. Each access list entry has a class/type that determines how the entry works.
»»»» type	body	string	false	none
»»»» accept	body	boolean	false	specifies if we accept or deny this particular access
»»»» username	body	username	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
»»»» groupname	body	groupname	false	a group name that is being in used in user management to specify a group name.
»»»» subnet	body	accessRouteSubnet	false	The definition of the subnet used by the nat and route accessRoute classes.
»»»»» anonymous	body	object	false	describes an IP subnet.
»»»»»» ipv6	body	boolean	false	whether this describes an IPv4 or an IPv6 subnet
»»»»»» netip	body	string	false	the network IP address.
»»»»»» prefix_length	body	integer	false	length of the prefix in CIDR notation
»»»»» anonymous	body	object	false	none
»»»»»» service	body	[oneOf]	false	[describes an IP UDP/TCP service or an icmp service]
»»»»»»» anonymous	body	portRange	false	Describes a layer4 (TCP/UDP) port or port-range. protocol may only be udp or tcp
»»»»»»»» protocol	body	layer4protocol	true	specifies a Layer 4 protocol (e.g. udp or tcp)
»»»»»»»» start_port	body	integer	true	The start port of the port range
»»»»»»»» end_port	body	integer	false	The end port of the port range. If not specified, the range will consist of only one single port (start_port)
»»»»»»» anonymous	body	icmpService	false	Describes an icmp service type. protocol is always icmp
»»»»»»»» protocol	body	layer4protocol	false	specifies a Layer 4 protocol (e.g. udp or tcp)
»»»»»»»» type	body	string	false	none
»»» anonymous	body	null	false	indicator that routes of this type should be deleted
»» type	body	string	false	the type of access list this item this is in the user/group.
»» anonymous	body	object	false	none
»»» anonymous	body	object	false	none
»» anonymous	body	object	false	none
»»» anonymous	body	object	false	none

Detailed descriptions

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.

»»»» subnet: The definition of the subnet used by the nat and route accessRoute classes. Each one is a subnet with one or more port ranges

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)

Enumerated Values

Parameter	Value
»»»» type	user
»»»» type	group
»»»» type	route
»»»» type	nat
»»»» type	all
»»»» type	all_vpn_clients
»»»» type	all_s2c_subnets
»»»»»»»» protocol	tcp
»»»»»»»» protocol	udp
»»»»»»»» protocol	icmp
»»»»»»»» protocol	tcp
»»»»»»»» protocol	udp
»»»»»»»» protocol	icmp
»»»»»»»» 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
»» type	access_from_ipv6
»» type	access_from_ipv4
»» type	access_to_ipv4
»» type	access_to_ipv6

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	access rules are successfully set	None
400	Bad Request	the rules are not formattted corrrectly or the specified user/group does not exist.	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "items_set": [
    {
      "username": "johann",
      "access_route": {}
    },
    {
      "username": "wolfgang",
      "access_route": null,
      "type": "access_to_ipv4"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/access/set',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

post__users_delete

Body parameter

{
  "users": [
    "niccolo@paganini.it"
  ]
}

Responses

Status	Meaning	Description	Schema
204	No Content	userprop was successfully deleted	None
400	Bad Request	invalid request args	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	userprop to be deleted was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "users": [
    "niccolo@paganini.it"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/users/delete',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
» users	body	[username]	false	users name list to delete.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__groups_delete

Body parameter

{
  "groups": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
204	No Content	userprop was successfully deleted	None
400	Bad Request	invalid request args	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	userprop to be deleted was not found	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "groups": [
    "string"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/delete',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
» groups	body	[groupname]	false	users name list to delete.

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

modifyUserPropGroupBulk

Body parameter

"[{ 'name': 'bob', 'auth_method': 'saml'}, {'name': 'bob', 'autologin': false, pw_strength: null }]"

Parameters

Name	In	Type	Required	Description
body	body	array[any]	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	changes to userproperties profile successfully done	None
400	Bad Request	user property creation has some problem like using an invalid property name or using wrong type (boolean vs string) or using a property that is not valid on this userproperty (group only attribute on a user or vice versa). Keys in the detailed error response are tuples (user, property).	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	user or group does not exist	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '[{ 'name': 'bob', 'auth_method': 'saml'}, {'name': 'bob', 'autologin': false, pw_strength: null }]';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/set',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

helper

various API function which functionality could be achieved purely on the frontend or with a combination of various backend calls but are provided to make these tasks easier or to not have a second implementation purely on the frontend (like parsing SAML metadata).

post__helper_get-saml-configuration

Body parameter

{
  "data": "string",
  "url": "http://example.com"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
400	Bad Request	Something went wrong parsing the data or fetching the metadata	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

const inputBody = '{
  "data": "string",
  "url": "http://example.com"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/helper/get-saml-configuration',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "configuration_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
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» data	body	string	false	The string that contains SAML Idp metadata in xml format
» url	body	string(uri)	false	the url from which the backend will fetch SAML Idp metadata from
» anonymous	body	object	false	none
» anonymous	body	object	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» configuration_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	true	none	the configuration value’s key.
»»» derived_from	configurationValueSource	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	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	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	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	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

certificate

APIs related to certificate management like parsing a certificate or querying information about a certificate

post__certificate_create

Body parameter

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Certificate has been generated.	Inline
400	Bad Request	there was some error while trying to generate the certificate	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

RequestJavaScript

const inputBody = '{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/certificate/create',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "certificate": "string",
  "private_key": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	certificateCreateRequest	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» certificate	pemEncodedCertificate(pem)	false	none	An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—–
» private_key	pemEncodedPrivateKey(pem)	false	none	An PEM encoded certificate. This the certificate representation that typically starts with —–BEGIN PRIVATE KEY—– followed by base64 encoding and ends with —–END PRIVATE KEY—–

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

logs

Querying the log database of OpenVPN Access Server

getLogReports

Body parameter

{
  "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": []
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	logDBRequestParameters	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	log reports entries	Inline
400	Bad Request	format of the filters is not valid	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» records	[logDBRecord]	false	none	none
»» timestamp	string(date-time)	true	none	record modification timestamp
»» node	any	true	none	AS node that created the log report
»» username	any	false	none	username that created the entry
»» start_time	any	false	none	start time of the event or just time of the event if duration is missing
»» duration	any	false	none	duration of the event in seconds
»» service	string	false	none	the service of OpenVPN Access Server that created the event
»» active	boolean	false	none	if the session is still active
»» auth	boolean	false	none	whether authentication succeeded or not
»» platform	any	false	none	the platform of the client.
»» version	any	false	none	the version of the OpenVPN component that implement the OpenVPN protocol
»» proto	string,null	false	none	the protocol being used
»» gui_version	any	false	none	the IV_GUI version the client reported.
»» real_address	string	false	none	the IP address the client is connected from
»» server_port	integer	false	none	the server side port the client connects/connected to
»» virtual_ipv4_address	string	false	none	the virtual or VPN address of the client
»» virtual_ipv6_address	string	false	none	none
»» session_id	string	false	none	internal session ID of the connection (this might be truncated)
»» api_method	string	false	none	description of the API method that was called
»» bytes_sent	integer	false	none	number of bytes sent
»» bytes_received	integer	false	none	number of bytes received
»» total_bytes	integer	false	none	total number of transferred bytes. (This seems and probably is redundant but currently we keep this as individual record in the backend database)
»» error	string	false	none	error message on auth failure
»» extra	string	false	none	service-specific data
» total	integer	false	none	total number of profiles that match if pagination is not in effect, this matches the size of the provided array

Enumerated Values

Property	Value
proto	tcp
proto	udp

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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": []
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/log/reports',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "records": [
    {
      "timestamp": "2019-08-24T14:15:22Z",
      "node": "vpn-12.example.com",
      "username": null,
      "start_time": null,
      "duration": null,
      "service": "WEB_ADMIN",
      "active": true,
      "auth": true,
      "platform": "android",
      "version": "2.6.11",
      "proto": "tcp",
      "gui_version": "de.blinkt.openvpn_0.7.48",
      "real_address": "1.2.7.8:23123",
      "server_port": 1194,
      "virtual_ipv4_address": "10.0.0.7",
      "virtual_ipv6_address": "fd00:f00f::b00f",
      "session_id": "gOB8vpI1MEr0vBnm",
      "api_method": "ConfigQuery",
      "bytes_sent": 0,
      "bytes_received": 0,
      "total_bytes": 0,
      "error": "LOCKOUT: user temporarily locked out due to multiple authentication failures",
      "extra": "string"
    }
  ],
  "total": 0
}

user

Userprop APIs that apply to managing users

post__userprop_mfa_generate-secret

Body parameter

{
  "username": "niccolo@paganini.it",
  "reset_secret": true,
  "locked": true
}

Responses

Status	Meaning	Description	Schema
200	OK	Operation successfully finished.	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason
404	Not Found	user not found	None

RequestJavaScript

const inputBody = '{
  "username": "niccolo@paganini.it",
  "reset_secret": true,
  "locked": true
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/userprop/mfa/generate-secret',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "totp_secret": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» username	body	username	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
» reset_secret	body	boolean	false	When set to false, a user that already has a token, the function will not generate a new secret. If not present, reset_secret is assumed to be false.
» locked	body	boolean	false	When reset_locked is set to true, this will be set the newed locked status

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» totp_secret	string	false	none	the RFC 6238 TOTP secret to allow enrollment of the user.

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

group

Userprop APIs that apply to managing groups

getgroupuserprops

Body parameter

{
  "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"
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	groupRequestParameters	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline
400	Bad Request	Some of the arguments are incorrect	errorReason
403	Forbidden	only admin users are allowed to use this 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	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	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	false	none	This object describes a single user property value. If it is
»»» admin	userPropValue	false	none	This object describes a single user property value. If it is
»»» autologin	userPropValue	false	none	This object describes a single user property value. If it is
»»» auth_method	userPropValue	false	none	This object describes a single user property value. If it is
»»» cc_commands	userPropValue	false	none	This object describes a single user property value. If it is
»»» totp	userPropValue	false	none	This object describes a single user property value. If it is
»»» password_strength	userPropValue	false	none	This object describes a single user property value. If it is
»»» allow_password_change	userPropValue	false	none	This object describes a single user property value. If it is
»»» reroute_gw	userPropValue	false	none	This object describes a single user property value. If it is
»»» allow_generate_profiles	userPropValue	false	none	This object describes a single user property value. If it is
»»» bypass_subnets	[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	groupLevelOnlyProps	false	none	this describes properties that are only are present for groups and not for users
»»» members	[string]	false	none	list of all users that are members of this group. This property will be only be present if members of the group are enumerate_memberate is true in the groupRequestParameters
»»» member_count	integer	false	none	the number of users that belong to this group.
»»» subnets	[IPsubNet]	false	none	The subnets assigned to this group. This list will be a mixed list of IPv4 and IPv6 subnets. The backend userprops are group_subnets and group_subnets6
»»» dynamic_ranges	[groupIpRange]	false	none	The dynamic ranges assigned to this group. This list will contain both IPv4 and IPv6 ranges. The backend userprops for this property are group_range and group_range6.
»»»» 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.

and

Name	Type	Required	Restrictions	Description
»» anonymous	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.<win
»»» cli_script_connect_win_user_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_win_admin_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_user_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
»»» cli_script_connect_mac_admin_disconnect	userPropValue	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	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	false	none	This object describes a single user property value. If it is

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "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"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/groups/list',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "total": 0,
  "profiles": [
    {
      "name": "string",
      "deny": {},
      "deny_web": {},
      "admin": {},
      "autologin": {},
      "auth_method": {},
      "cc_commands": {},
      "totp": {},
      "password_strength": {},
      "allow_password_change": {},
      "reroute_gw": {},
      "allow_generate_profiles": {},
      "bypass_subnets": [],
      "members": [],
      "member_count": 0,
      "subnets": [],
      "dynamic_ranges": [],
      "cli_script_connect_win_user_connect": {},
      "cli_script_connect_win_user_disconnect": {},
      "cli_script_connect_win_admin_connect": {},
      "cli_script_connect_win_admin_disconnect": {},
      "cli_script_connect_mac_user_connect": {},
      "cli_script_connect_mac_user_disconnect": {},
      "cli_script_connect_mac_admin_connect": {},
      "cli_script_connect_mac_admin_disconnect": {},
      "cli_script_connect_win_env": {},
      "cli_script_connect_mac_env": {}
    }
  ]
}

misc

APIs that do not fit in any other category

get_server_config

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	serverConfig

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const headers = {
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/config',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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
}

getCWSconfig

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	WebsiteConfig

This operation does not require authentication

RequestJavaScript

const headers = {
  'Accept':'application/json'
};

fetch('/api/ui/config',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "header_image": "string",
  "hide_footer": "string",
  "enabled_auth_methods": [
    "saml",
    "userandpassword"
  ],
  "login_text": "Enter your TOTP Authentication code."
}

maintainance

post__server_failover-test

Body parameter

{
  "failover.mode": "ucarp",
  "ucarp.addr": "192.168.188.254",
  "ucarp.secret": "sharedsecret",
  "dbpush.hosts.0.enable": "true",
  "dbpush.hosts.0.public": "grace.hopper",
  "dbpush.hosts.0.internal": "PRIMARY",
  "dbpush.hosts.0.username": "root",
  "dbpush.hosts.1.enable": "true",
  "dbpush.hosts.1.public": "ada.lovelace",
  "dbpush.hosts.1.internal": "SECONDARY",
  "dbpush.hosts.1.username": "root",
  "dbpush.hosts.1.password": "",
  "dbpush.hosts.1.ssh_port": "22"
}

Responses

Status	Meaning	Description	Schema
200	OK	Results of the failoover test.	failOverTestStatus
400	Bad Request	Failover test initialisation failed.	errorReasonDetail
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = '{
  "failover.mode": "ucarp",
  "ucarp.addr": "192.168.188.254",
  "ucarp.secret": "sharedsecret",
  "dbpush.hosts.0.enable": "true",
  "dbpush.hosts.0.public": "grace.hopper",
  "dbpush.hosts.0.internal": "PRIMARY",
  "dbpush.hosts.0.username": "root",
  "dbpush.hosts.1.enable": "true",
  "dbpush.hosts.1.public": "ada.lovelace",
  "dbpush.hosts.1.internal": "SECONDARY",
  "dbpush.hosts.1.username": "root",
  "dbpush.hosts.1.password": "",
  "dbpush.hosts.1.ssh_port": "22"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/failover-test',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "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"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» additionalProperties	body	string	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

post__server_failover-init

Body parameter

null

Responses

Status	Meaning	Description	Schema
200	OK	Secondary node setup was successful.	None
400	Bad Request	Something went wrong during secondary node setup	errorReason
403	Forbidden	only admin users are allowed to use this API	errorReason

To perform this operation, you must be authenticated by means of one of the following methods: AuthToken

RequestJavaScript

const inputBody = 'null';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/server/failover-init',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Responsejson

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

Parameters

Name	In	Type	Required	Description
body	body	any	false	none

standard response when there insufficient rights to use an API.

{
  "message": "Insufficient privileges to use this API"
}

Schemas

WebsiteConfig

Provides the information about the website personality and other web-site wide configuration that must be available without authentication

Properties

Name	Type	Required	Restrictions	Description
header_image	string,null	false	none	An URI to an alternative header image that is customised. If not present use default logo
hide_footer	string,null	false	none	If true then hide footer
enabled_auth_methods	[string]	true	none	A list of enabled authentication methods. UI should only offer enabled methods. These are NOT the backend methods but rather the ways of providing credentials regardless of the backend authentication method. The userandpasswordwithmfa method will provide the user with username, password and TOTP field for the login to make allow entering both factors in one step instead of two.
login_text	string,null	false	none	Alternative login text.

json

{
  "header_image": "string",
  "hide_footer": "string",
  "enabled_auth_methods": [
    "saml",
    "userandpassword"
  ],
  "login_text": "Enter your TOTP Authentication code."
}

profileType

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	autologin
anonymous	userlogin
anonymous	generic
anonymous	epki-generic

json

"autologin"

username

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

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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

"niccolo@paganini.it"

groupname

a group name that is being in used in user management to specify a group name.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	a group name that is being in used in user management to specify a group name.

json

"string"

installerType

Type of the installer binary that should be created for installation.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Type of the installer binary that should be created for installation.

Enumerated Values

Property	Value
anonymous	win_v3
anonymous	mac_v3
anonymous	win
anonymous	mac
anonymous	ios
anonymous	android
anonymous	linux

json

"win_v3"

certProfileSorting

specifies by which attribute profiles should be sorted

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	specifies by which attribute profiles should be sorted

Enumerated Values

Property	Value
anonymous	serial
anonymous	username
anonymous	not_before
anonymous	type
anonymous	not_after
anonymous	tls_crypt_v2
anonymous	last_used
anonymous	algorithm

json

"serial"

userSorting

specifies by which attribute profiles should be sorted

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	specifies by which attribute profiles should be sorted

Enumerated Values

Property	Value
anonymous	admin
anonymous	name
anonymous	autologin
anonymous	group

json

"admin"

groupSorting

specifies by which attribute groups should be sorted

Properties

None

json

"name"

logDBSortingFields

Enum representing valid sorting fields for LogDB.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Enum representing valid sorting fields for LogDB.

Enumerated Values

Property	Value
anonymous	node
anonymous	username
anonymous	service
anonymous	duration
anonymous	active
anonymous	virtual_ipv4_address
anonymous	bytes_received
anonymous	bytes_sent
anonymous	timestamp
anonymous	error
anonymous	version
anonymous	gui_version
anonymous	platform

json

"node"

sortingDirection

The direction of sorting

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The direction of sorting

Enumerated Values

Property	Value
anonymous	asc
anonymous	desc

json

"asc"

UserCertProfile

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

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	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

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",
  "device_id": "string",
  "comment": "My toaster running Doom",
  "profile_type": "autologin",
  "tls_crypt_v2": true,
  "last_used": "2019-08-24",
  "username": "string"
}

usertype

type of the user

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	type of the user

Enumerated Values

Property	Value
anonymous	admin
anonymous	user

json

"admin"

userproperties

Properties

Name	Type	Required	Restrictions	Description
requires_mfa_enrollment	boolean	true	none	if present, this user needs to finish MFA enrollment
user_type	usertype	false	none	type of the user
mfa_secret	string	false	none	This is an optional field that is only visible if the user has not enrolled yet or is an admin user.
allowed_profiles	[profileType]	false	none	A list of profiles types allowed for the user. Sorted by preference.
enforce_strong_passwords	boolean	false	none	If true, than checking for strong password is required.
allow_password_change	boolean	false	none	Indicates whether password change is allowed for the user.

json

{
  "requires_mfa_enrollment": true,
  "user_type": "admin",
  "mfa_secret": "string",
  "allowed_profiles": [
    "autologin"
  ],
  "enforce_strong_passwords": true,
  "allow_password_change": true
}

MFAChallenge

Properties

Name	Type	Required	Restrictions	Description
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.

json

{
  "challenge": "If you could be any animal, what would you be and why?",
  "echo": true,
  "challenge_context": "812jh3a8s"
}

MFAResponse

Properties

Name	Type	Required	Restrictions	Description
response	string(password)	false	none	the user’s response to the MFA challenge
challenge_context	string	false	none	The challenge context that was in the MFAChallenge.
username	string	true	none	The user name for login

json

{
  "response": "pa$$word",
  "challenge_context": "FJAIIXMAIOFLGAK23",
  "username": "string"
}

certificateSerial

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(int64)	false	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.

json

"1708464983752887'"

certificateCommonName

The common name of the certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string,null	false	none	The common name of the certificate.

json

"OpenVPN VPN server CA"

userAndPwLogin

Properties

Name	Type	Required	Restrictions	Description
username	string	true	none	The user name for login. Note that if this is case-sensitive or not depends on the OpenVPN Access Server configuration.
password	string	true	none	The password for login in clear text
totp	string	false	none	Optional TOTP token for the user when wishing to do all MFA credentials in one go

json

{
  "username": "string",
  "password": "string",
  "totp": "string"
}

samlLogin

Properties

Name	Type	Required	Restrictions	Description
assertion	string(xml)	true	none	SAML Assertion in xml format , encoded as base64-string
relay_state	string	false	none	Optional relay state identifying the type of SAML request. If not passed or empty, defaults to cws

json

{
  "assertion": "string",
  "relay_state": "vpnauth~nod1~Dfk3287761d"
}

loginResponse

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» user_properties	userproperties	false	none	none
» username	string	true	none	username of the authenticated user

and

Name	Type	Required	Restrictions	Description
anonymous	authTokenResponse	false	none	none

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"
}

authTokenResponse

Properties

Name	Type	Required	Restrictions	Description
auth_token	string	true	none	An opaque token that is used to access protected APIs
expires_after	string(%a %b %d %Y %-H:%-M:%-S GMT%z (%Z))	true	none	date in UTC when token expires
renewable_until	string(%a %b %d %Y %-H:%-M:%-S GMT%z (%Z))	true	none	date in UTC when the token is no longer renewable

json

{
  "auth_token": "string",
  "expires_after": "string",
  "renewable_until": "string"
}

profileDeleteCode

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	none

Enumerated Values

Property	Value
anonymous	{“204”:null,“description”:“profile successfully deleted”}
anonymous	{“404”:null,“description”:“profile to be deleted was not found”}
anonymous	{“403”:null,“description”:“profile to be deleted is not owned by the user or another error”}

json

{
  "204": null,
  "description": "profile successfully deleted"
}

clientReason

the reason given to the client why it is being disconnected.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the reason given to the client why it is being disconnected.

json

"Client disconnected for administrative reasons"

adminReason

The reason that will be logged why a client was disconnected

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The reason that will be logged why a client was disconnected

json

"John should not be working after hours"

vpnConnectionID

Properties

Name	Type	Required	Restrictions	Description
daemon_id	daemonID	true	none	an ID that identifies the OpenVPN daemon that the client is connected to
client_id	clientID	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.

json

{
  "daemon_id": "openvpn_7",
  "client_id": 7
}

errorReason

Properties

Name	Type	Required	Restrictions	Description
reason	string	true	none	a user-friendly message of reason of API failure, allowed to be displayed
title	string	false	none	a title describing the error message

json

{
  "reason": "Your password must not include parts of Cthulhu's chant.",
  "title": "Password validation failed"
}

errorReasonDetail

an errorReason that has been extended to provide specific errors for specific fields. The references are dependent on the fields used in the query. E.g. when setting configuration keys the detail keys are the fields trying to be set.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	errorReason	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» detail	object	false	none	errorReasons that specify the errorReason for a specific sub object
»» additionalProperties	errorReason	false	none	none

json

{
  "reason": "config values had errors",
  "detail": {
    "host.name": "Contains invalid character %",
    "server.port": "Must be an integer between 1 and 65335"
  }
}

configurationProfile

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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.

json

"string"

certificateAlgorithm

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).

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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).

json

"rsa2048"

certificateType

The type of certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The type of certificate.

Enumerated Values

Property	Value
anonymous	ca
anonymous	old_ca
anonymous	cross_ca
anonymous	client

json

"ca"

certificateDetails

Properties

Name	Type	Required	Restrictions	Description
serial	certificateSerial	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	true	none	The common name of the certificate.
algorithm	certificateAlgorithm	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.

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"
}

certificateInformationDetails

Provides more information about a certificate

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» sha256fp	certificateFingerprint	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

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
}

certificateAuthorityDetails

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateDetails	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» cert_type	certificateType	true	none	The type of certificate.
» client_profiles	integer	true	none	the number of VPN client profiles are issued by this CA.

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
}

certificateCreateRequest

A request to generate a certificate and sign it. If the signing_ca and its private key are provided (via signing_ca_key OR signing_ca_config_key) the generated certificate will signed by the CA, otherwise the certificate will be self-signed.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	certificateRequest	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» cert_template	string	true	none	the template to use when creating the certificate. This mainly controls the key usage (KU) and extend key usage (EKU) attributes of the certificate
» days_to_expiry	integer	false	none	number of days while certificate is considered valid
» private_key_passphrase	string	false	none	passhprase for the certificate’s private key
» signing_ca	pemEncodedCertificate	false	none	An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—–
» subj_alt_dns_names	[string]	false	none	a list of DNS names that should be added as SubjectAlternativeName DNSJake in the certificate if the cert_template is webserver.
» signing_ca_key	pemEncodedPrivateKey	false	none	An PEM encoded certificate. This the certificate representation that typically starts with —–BEGIN PRIVATE KEY—– followed by base64 encoding and ends with —–END PRIVATE KEY—–
» signing_ca_config_key	any	false	none	the name of a configuration key (e.g. cs.priv.key) that will be used to check the certificate validity
» signing_ca_private_key_passphrase	string	false	none	passhprase for signing CA’s private key

Enumerated Values

Property	Value
cert_template	spcert
cert_template	ca
cert_template	intermediate_ca
cert_template	webserver
cert_template	server
cert_template	client
cert_template	hybrid

json

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA",
  "cert_template": "spcert",
  "days_to_expiry": 365,
  "private_key_passphrase": "string",
  "signing_ca": "string",
  "subj_alt_dns_names": [
    "vpn-server.example.com"
  ],
  "signing_ca_key": "string",
  "signing_ca_config_key": null,
  "signing_ca_private_key_passphrase": "string"
}

certificateRequest

Properties

Name	Type	Required	Restrictions	Description
algorithm	certificateAlgorithm	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).
common_name	certificateCommonName	false	none	The common name of the certificate.

json

{
  "algorithm": "secp384r1",
  "common_name": "my shiny new CA"
}

integerConfigurationValue

A configuration value that is expressed as an integer.

Properties

Name	Type	Required	Restrictions	Description
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

json

{
  "value": 0,
  "default_value": 0,
  "max_value": 0,
  "min_value": 0
}

stringConfigurationValue

A configuration value that is expressed as a string. Either value or redacted_value is present

Properties

Name	Type	Required	Restrictions	Description
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

Enumerated Values

Property	Value
type_hint	ipv4Address
type_hint	ipv6Address
type_hint	ipAddress
type_hint	hostname
type_hint	pemCertificate
type_hint	pemPrivateKey

json

{
  "value": "string",
  "redacted_value": "PEM encoded private key [rsa2048]",
  "default_value": "string",
  "allowed_values": [
    "string"
  ],
  "type_hint": "ipv4Address"
}

booleanConfigurationValue

Properties

Name	Type	Required	Restrictions	Description
value	boolean	false	none	none
default_value	boolean	false	none	The default value for the configuration.

json

{
  "value": true,
  "default_value": true
}

customConfigurationValue

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.

Properties

Name	Type	Required	Restrictions	Description
value	string	false	none	none

json

{
  "value": "string"
}

configurationValueSource

the source that the current values has be derived from.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the source that the current values has be derived from.

Enumerated Values

Property	Value
anonymous	default
anonymous	local_db
anonymous	cluster_db
anonymous	mysql_standalone_db
anonymous	as_conf
anonymous	environment
anonymous	runtime
anonymous	other

json

"default"

configurationItemKey

the configuration value’s key.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the configuration value’s key.

json

"vpn.server.cipher"

configurationItem

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.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» name	configurationItemKey	true	none	the configuration value’s key.
» derived_from	configurationValueSource	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	false	none	A configuration value that is expressed as an integer.

xor

Name	Type	Required	Restrictions	Description
» anonymous	booleanConfigurationValue	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	stringConfigurationValue	false	none	A configuration value that is expressed as a string. Either value or redacted_value is present

xor

Name	Type	Required	Restrictions	Description
» anonymous	customConfigurationValue	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.

Enumerated Values

Property	Value
type	custom
type	integer
type	boolean
type	string
category	deprecated
category	removed
category	normal
category	required
category	derived
category	advanced
category	custom

json

{
  "name": "vpn.server.cipher",
  "derived_from": "default",
  "type": "custom",
  "description": "string",
  "category": "deprecated",
  "value": 0,
  "default_value": 0,
  "max_value": 0,
  "min_value": 0
}

pemEncodedCertificate

An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—–

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(pem)	false	none	An PEM encoded certificate. This the certificate representation that starts with —–BEGIN CERTIFICATE—– followed by base64 encoding and ends with —–END CERTIFICATE—–

json

"string"

pemEncodedPrivateKey

An PEM encoded certificate. This the certificate representation that typically starts with —–BEGIN PRIVATE KEY—– followed by base64 encoding and ends with —–END PRIVATE KEY—–

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(pem)	false	none	An PEM encoded certificate. This the certificate representation that typically starts with —–BEGIN PRIVATE KEY—– followed by base64 encoding and ends with —–END PRIVATE KEY—–

json

"string"

certificateFingerprint

The SHA256 hash of the certificate body, also known as the fingerprint of the certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(sha256)	false	none	The SHA256 hash of the certificate body, also known as the fingerprint of the certificate.

json

"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"

apiEndpoint

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	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.

json

"https://node1:945"

restartMode

the requested mode to restart AS. - Warm will only restart the internal services that are needed to be restarted - cold will restart OpenVPN Access Server completely - systemctl instruct OpenVPN Access Server to initiate a restart via systemd/systemctl - server_agent instruct OpenVPN Access Server to initiate a full reinit of the server agent, including re-reading the configuration in as.conf. If we don’t need to re-read the configuration from a new DB URI (e.g. after converting the DB or creating a cluster) - ‘cold’ should generally be enough, as it will revalidate the individual services’ need to reinit, based on the information in the DB being used at that moment.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the requested mode to restart AS. - Warm will only restart the internal services that are needed to be restarted - cold will restart OpenVPN Access Server completely - systemctl instruct OpenVPN Access Server to initiate a restart via systemd/systemctl - server_agent instruct OpenVPN Access Server to initiate a full reinit of the server agent, including re-reading the configuration in as.conf. If we don’t need to re-read the configuration from a new DB URI (e.g. after converting the DB or creating a cluster) - ‘cold’ should generally be enough, as it will revalidate the individual services’ need to reinit, based on the information in the DB being used at that moment.

Enumerated Values

Property	Value
anonymous	cold
anonymous	warm
anonymous	dry_run
anonymous	systemctl
anonymous	server_agent

json

"cold"

connectedVPNClient

a connected VPN client with the current information about this client

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	vpnConnectionID	false	none	none

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

json

{
  "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"
}

clientID

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.

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	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.

json

daemonID

an ID that identifies the OpenVPN daemon that the client is connected to

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	an ID that identifies the OpenVPN daemon that the client is connected to

json

"openvpn_7"

vpnDaemonStatus

status of a VPN daemon

Properties

Name	Type	Required	Restrictions	Description
dco	boolean	false	none	if DCO is used on this daemon instance
version	string	false	none	the OpenVPN 2.x version of the daemon

json

{
  "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"
}

dcoModuleStatus

Properties

Name	Type	Required	Restrictions	Description
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

json

{
  "available": true,
  "version": "0.2.20230323"
}

logDBRecord

Properties

Name	Type	Required	Restrictions	Description
timestamp	string(date-time)	true	none	record modification timestamp
node	any	true	none	AS node that created the log report
username	any	false	none	username that created the entry
start_time	any	false	none	start time of the event or just time of the event if duration is missing
duration	any	false	none	duration of the event in seconds
service	string	false	none	the service of OpenVPN Access Server that created the event
active	boolean	false	none	if the session is still active
auth	boolean	false	none	whether authentication succeeded or not
platform	any	false	none	the platform of the client.
version	any	false	none	the version of the OpenVPN component that implement the OpenVPN protocol
proto	string,null	false	none	the protocol being used
gui_version	any	false	none	the IV_GUI version the client reported.
real_address	string	false	none	the IP address the client is connected from
server_port	integer	false	none	the server side port the client connects/connected to
virtual_ipv4_address	string	false	none	the virtual or VPN address of the client
virtual_ipv6_address	string	false	none	none
session_id	string	false	none	internal session ID of the connection (this might be truncated)
api_method	string	false	none	description of the API method that was called
bytes_sent	integer	false	none	number of bytes sent
bytes_received	integer	false	none	number of bytes received
total_bytes	integer	false	none	total number of transferred bytes. (This seems and probably is redundant but currently we keep this as individual record in the backend database)
error	string	false	none	error message on auth failure
extra	string	false	none	service-specific data

Enumerated Values

Property	Value
proto	tcp
proto	udp

json

{
  "timestamp": "2019-08-24T14:15:22Z",
  "node": "vpn-12.example.com",
  "username": null,
  "start_time": null,
  "duration": null,
  "service": "WEB_ADMIN",
  "active": true,
  "auth": true,
  "platform": "android",
  "version": "2.6.11",
  "proto": "tcp",
  "gui_version": "de.blinkt.openvpn_0.7.48",
  "real_address": "1.2.7.8:23123",
  "server_port": 1194,
  "virtual_ipv4_address": "10.0.0.7",
  "virtual_ipv6_address": "fd00:f00f::b00f",
  "session_id": "gOB8vpI1MEr0vBnm",
  "api_method": "ConfigQuery",
  "bytes_sent": 0,
  "bytes_received": 0,
  "total_bytes": 0,
  "error": "LOCKOUT: user temporarily locked out due to multiple authentication failures",
  "extra": "string"
}

licenseInfo

fields that are common to licensing options and the licensing method that currently in. Will also contain additional fields depending on the licensing_type in use.

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» licensing_type	string	false	none	the method that Access Server is licensed
» current_cc	integer	false	none	the number of current concurrent connections
» max_cc	integer	false	none	the maximum amount of connections that this license allows to use. For license types are single node (aws, fixed, unlicensed) this is also the limit for all connections. For shared licenses (subscription) this denotes the total number of connections in the subscription and the current number of allocated connection for an Access Server is denoted in cc_limit.

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	fixedLicenseInfo	false	none	describes the current licensing information about OpenVPN Access Server. An OpenVPN Access Server can have multiple fixed licenses assigned to it and allowed connections of all the valid (not expired) licenses are summed up.

xor

Name	Type	Required	Restrictions	Description
» anonymous	subscriptionInfo	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	unlicensedInfo	false	none	(dummy) information when AS is not currently licensed

xor

Name	Type	Required	Restrictions	Description
» anonymous	awsTieredLicenseInfo	false	none	none

Enumerated Values

Property	Value
licensing_type	unlicensed
licensing_type	subscription
licensing_type	awstiered
licensing_type	fixed

json

{
  "licensing_type": "unlicensed",
  "current_cc": 3,
  "max_cc": 13,
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

unlicensedInfo

(dummy) information when AS is not currently licensed

Properties

None

json

{}

fixedLicenseInfo

describes the current licensing information about OpenVPN Access Server. An OpenVPN Access Server can have multiple fixed licenses assigned to it and allowed connections of all the valid (not expired) licenses are summed up.

Properties

Name	Type	Required	Restrictions	Description
fixed_licenses	[object]	false	none	none
» expiry	string(date-time)	false	none	expiry date of the license.
» key	string	false	none	the key of the fixed license
» max_cc	integer	false	none	maximum amount of connection for this fixed license.

json

{
  "fixed_licenses": [
    {
      "expiry": "2019-08-24T14:15:22Z",
      "key": "string",
      "max_cc": 0
    }
  ]
}

awsTieredLicenseInfo

Properties

Name	Type	Required	Restrictions	Description
region	string	false	none	the AWS region
product_code	string	false	none	the AWS product code that identifies this license
instance_id	string	false	none	the AWS instance ID

json

{
  "region": "eu-central-1",
  "product_code": "3ihdqli79gl9v2jnlzs6nq60h",
  "instance_id": "i-0c1ac1ca2f4b4a23b"
}

subscriptionInfo

Properties

Name	Type	Required	Restrictions	Description
agent_id’	string	false	none	the identifier the client uses to connect to STS
agent_disabled	boolean	false	none	none
cc_limit	integer	false	none	the limit of connection assigned to the Access Server. This can dynamically change.
error	string,null	false	none	if an error occurred this will be set to a human-readable error message
fallback_cc’	integer	false	none	the amount of connection that the subscription will revert to if the subscription server cannot be reached for an extended time (grace_period)
grace_period	integer	false	none	number of days after which the subscription will revert to fallback_cc amount of connections
last_successful_update	string(date-time)	false	none	the last time the subscription was successfully updated
total_cc	integer	false	none	the total number of current connections for the subscription over all Access Server that use this subscription. Basically the current_cc of all OpenVPN Access Server using this subscription summed up.
name	string	false	none	A name given to the subscription.
subkey	string	false	none	The subkey that uniquely identifies the subscription on the backend.
billing_id	string	false	none	An opaque identifier that allows identifying the subscription on the billing portal.
next_update	string(date-time)	false	none	when the next update to the subscription server is scheduled
updates_failed	integer	false	none	the number of updates that failed since the last successful update.
notes	[string]	false	none	both server generated and locally generated additional notes to display to the user
overdraft	boolean	false	none	Subscription is currently in overdraft mode
server	string	false	none	the server that is used to for subscription tracking
type	string	false	none	Type of the subscription as reported by the STS server
state	string	false	none	the current state of the subscription agent

Enumerated Values

Property	Value
state	SUBSCRIPTION_OK
state	SUBSCRIPTION_EXPIRED
state	NOT_CONFIGURED
state	AGENT_DISABLED
state	SUBSCRIPTION_INVALID
state	SUBSCRIPTION_ENDED
state	SUBSCRIPTION_PAUSED
state	STSTRACK_ERROR
state	REQUEST_ERROR

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"
}

profileToken

this represent a (typically one-time) token that can be used to retrieve a profile from Access Server

Properties

Name	Type	Required	Restrictions	Description
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	false	none	none
usages	integer	false	none	how often this token can be used to retrieve a profile

json

{
  "token": "a4aL62OFooAjPu4wu6MQCvcmY070hu8B",
  "username": "arne@openvpn.net",
  "expires": "2019-08-24T14:15:22Z",
  "profile_type": "autologin",
  "usages": 1
}

userPropUser

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	userLevelOnlyProps	false	none	this describes the properties that are only allowed on the user level itself are not inheritable from other levels

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

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
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
    }
  }
}

userPropUserSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	userLevelOnlyProps	false	none	this describes the properties that are only allowed on the user level itself are not inheritable from other levels

and

Name	Type	Required	Restrictions	Description
anonymous	userPropScriptsSet	false	none	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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "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"
  }
}

userPropGroup

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	groupLevelOnlyProps	false	none	this describes properties that are only are present for groups and not for users

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

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
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
    }
  }
}

userPropGroupSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	groupLevelOnlyProps	false	none	this describes properties that are only are present for groups and not for users

and

Name	Type	Required	Restrictions	Description
anonymous	userPropScriptsSet	false	none	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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ],
  "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"
  }
}

userPropUserDefault

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userProp	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

and

Name	Type	Required	Restrictions	Description
anonymous	defaultUserOnlyProps	false	none	this describes properties that are only are present for groups and not for users

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» group	string	false	none	the group a user belongs too (conn_group)

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"
}

userPropUserDefaultSet

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	userPropSet	false	none	The same as userProp schema. With the difference that it used solely for setting user properties. This means that all fields here is set directly, instead of wraping them in userPropValue object.

and

Name	Type	Required	Restrictions	Description
anonymous	defaultUserOnlyProps	false	none	this describes properties that are only are present for groups and not for users

and

Name	Type	Required	Restrictions	Description
anonymous	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.<win

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» group	string	false	none	the group a user belongs too (conn_group)

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "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"
}

defaultUserOnlyProps

this describes properties that are only are present for groups and not for users

Properties

Name	Type	Required	Restrictions	Description
def_deny	boolean	false	none	If this is set to true user accounts will not be created if they are not listed in userprop. Normally, if an external auth is used (e.g. LDAP), then a user will automatically create if the external authentication system indicates a successful login.

json

{
  "def_deny": true
}

groupLevelOnlyProps

this describes properties that are only are present for groups and not for users

Properties

Name	Type	Required	Restrictions	Description
members	[string]	false	none	list of all users that are members of this group. This property will be only be present if members of the group are enumerate_memberate is true in the groupRequestParameters
member_count	integer	false	none	the number of users that belong to this group.
subnets	[IPsubNet]	false	none	The subnets assigned to this group. This list will be a mixed list of IPv4 and IPv6 subnets. The backend userprops are group_subnets and group_subnets6
dynamic_ranges	[groupIpRange]	false	none	The dynamic ranges assigned to this group. This list will contain both IPv4 and IPv6 ranges. The backend userprops for this property are group_range and group_range6.

json

{
  "members": [
    "niccolo@paganini.it",
    "hillary@hahn.us",
    "yoyoma"
  ],
  "member_count": 0,
  "subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ],
  "dynamic_ranges": [
    {
      "ipv6": true,
      "first_ip": "fd00::18cc:1b01:a772:50e1",
      "last_ip": "fd00::18cc:1b01:a772:80e1"
    }
  ]
}

userLevelOnlyProps

this describes the properties that are only allowed on the user level itself are not inheritable from other levels

Properties

Name	Type	Required	Restrictions	Description
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]	false	none	The IP addresses and port-ranges that are exposed on this client.
dmz_ipv6	[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]	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.

Enumerated Values

Property	Value
mfa_status	pending
mfa_status	disabled
mfa_status	enrolled

json

{
  "password_defined": true,
  "mfa_status": "pending",
  "totp_locked": true,
  "group": "stringsection",
  "static_ipv4": "string",
  "static_ipv6": "string",
  "dmz_ip": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "dmz_ipv6": [
    {
      "ip": "123.7.3.1",
      "start_port": 7000,
      "end_port": 7111,
      "protocol": "udp"
    }
  ],
  "compile": true,
  "totp_secret": "string",
  "totp_admin_only": true,
  "client_to_server_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ]
}

userPropValue

This object describes a single user property value. If it is

Properties

Name	Type	Required	Restrictions	Description
anonymous	object,null	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.

Enumerated Values

Property	Value
inherited_source_type	default
inherited_source_type	implicit_default
inherited_source_type	group
inherited_source_type	configuration

json

{
  "value": "string",
  "inherited": true,
  "inherited_source_type": "default",
  "inherited_source_name": "administrators"
}

userProp

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

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	the name of the user or group.
deny	userPropValue	false	none	This object describes a single user property value. If it is
deny_web	userPropValue	false	none	This object describes a single user property value. If it is
admin	userPropValue	false	none	This object describes a single user property value. If it is
autologin	userPropValue	false	none	This object describes a single user property value. If it is
auth_method	userPropValue	false	none	This object describes a single user property value. If it is
cc_commands	userPropValue	false	none	This object describes a single user property value. If it is
totp	userPropValue	false	none	This object describes a single user property value. If it is
password_strength	userPropValue	false	none	This object describes a single user property value. If it is
allow_password_change	userPropValue	false	none	This object describes a single user property value. If it is
reroute_gw	userPropValue	false	none	This object describes a single user property value. If it is
allow_generate_profiles	userPropValue	false	none	This object describes a single user property value. If it is
bypass_subnets	[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.

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
    }
  ]
}

userPropSet

The same as userProp schema. With the difference that it 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
name	string	false	none	the name of the user or group.
deny	boolean	false	none	none
deny_web	boolean	false	none	none
admin	boolean	false	none	none
autologin	boolean	false	none	none
auth_method	string	false	none	none
cc_commands	string	false	none	none
totp	boolean	false	none	none
password_strength	boolean	false	none	none
allow_password_change	boolean	false	none	none
reroute_gw	boolean	false	none	none
allow_generate_profiles	boolean	false	none	none
bypass_subnets	[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.

json

{
  "name": "string",
  "deny": true,
  "deny_web": true,
  "admin": true,
  "autologin": true,
  "auth_method": "string",
  "cc_commands": "string",
  "totp": true,
  "password_strength": true,
  "allow_password_change": true,
  "reroute_gw": true,
  "allow_generate_profiles": true,
  "bypass_subnets": [
    {
      "prefix_length": 21,
      "netip": "131.234.72.0",
      "ipv6": false
    }
  ]
}

userPropScripts

Client side scripting: prop_cli.script.<win|mac|all>.<user|admin>.<connect|disconnect>
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	false	none	This object describes a single user property value. If it is
cli_script_connect_win_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_win_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_win_admin_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_user_connect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_user_disconnect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_admin_connect	userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_admin_disconnect	userPropValue	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	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	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

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	false	none	none
error	[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	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	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]	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	true	none	none
installers	[installerType]	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	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	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	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	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	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	clusterProps	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	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	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	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	true	none	Type of the installer binary that should be created for installation.
profile_type	profileType	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	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	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	false	none	specifies by which attribute profiles should be sorted
» filters	object	false	none	none
»» user	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» serial_number	filterInteger	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» tls_crypt_v2	filterBool	false	none	This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
»» last_used	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	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	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	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» signing_ca_cn	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» anywhere	filterAnywhere	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	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	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	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»»» group	filterString	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	false	none	filters that can be applied to both user and group requests

continued

Name	Type	Required	Restrictions	Description
» users	[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	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	false	none	This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
autologin	filterBool	false	none	This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
anywhere	filterAnywhere	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	true	none	none
username	username	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	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	false	none	Enum representing valid sorting fields for LogDB.
» filters	object	false	none	none
»» start_time	filterTimeOrDuration	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	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	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» node	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» username	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» active	filterBool	false	none	This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
»» error	filterBool	false	none	This specifies a filter that filter on a bool. Since it is a bool, the operation is always equal.
»» service	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» virtual_ipv4_address	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» bytes_sent	filterBandwidth	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» bytes_received	filterBandwidth	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» gui_version	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» version	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» platform	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
»» anywhere	filterAnywhere	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

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

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	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	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	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	false	none	filters that can be applied to both user and group requests

continued

Name	Type	Required	Restrictions	Description
» enumerate_members	enumerateMembersParameter	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]	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	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	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
» groupname	filterString	false	none	This specifies that the result should be filtered by this attribute with the specified operation.
» username	filterString	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]	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]	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	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	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	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	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	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	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	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	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

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	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	false	none	a group name that is being in used in user management to specify a group name.
subnet	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

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	false	none	describes an IP subnet.

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» service	[IpService]	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	false	none	The result of a single failover test.
license_primary	failOverTestResult	false	none	The result of a single failover test.
license_secondary	failOverTestResult	false	none	The result of a single failover test.
connectivity	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://<ACCESS_SERVER>/rest/<METHOD>

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://<ACCESS_SERVER>/rest/<METHOD>

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://<ACCESS_SERVER>/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: <base64_encoded_user>

VPN-Session-Token: <base64_encoded_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).

Request

curl -u 'username:password' https://<ACCESS_SERVER>/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:

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
```
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.
The client presents the challenge to the user (e.g., "What is 1 x 3?"). The user enters the response.
The client then resubmits the request with the challenge response in the format specified by the server.
If the server validates the response, the requested connection profile is returned.

Challenge/response authentication details

Receiving a challenge: When the client requests a connection profile (e.g., GetUserlogin), but the server needs further validation, it responds with a challenge.
Understanding the challenge message: The challenge message follows the format CRV1: <flags>:<state_id>:<username_base64>:<challenge_text>, 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.
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.
Resubmitting the response: Once the user responds, the client resubmits the request to the server.
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

<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)</Message>
</Error>

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

Initial request:

curl -u test:mypass https://ACCESS_SERVER/rest/GetUserlogin

Server response (challenge):

<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)</Message>
</Error>

The user responds to the challenge question, "What is 1x3?" with the answer 3.

The client resubmits the request:

curl -u "test:CRV1::miwN39AlF4k40Fd8X8r9j74FuOoaJKJM::3" https://ACCESS_SERVER/rest/GetUserlogin

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, 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

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):

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>AUTH_FAILED: Server Agent XML method requires authentication (9007)</Message>
</Error>

Permission denied (user lacks autologin privileges):

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Internal Server Error</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>NEED_AUTOLOGIN: User 'USERNAME' lacks autologin privilege (9000)</Message>
</Error>

User not enrolled for authentication:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Access denied</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>You must enroll this user in Authenticator first before you are allowed to retrieve a connection profile. (9008)</Message>
</Error>

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.
```
<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>Ovpn-WebAuth: providername,flags</Message>
</Error>
```