REST API

Web API v0.1

OpenVPN Access Server Web API v0.1

This API is everything a web API needs to implement the functionality of downloading profiles/clients etc and implement the admin interface.

In this document we use the following convention for naming:

field names - snake case
URLs - dashes
everything else - camel case

The API allows proxying requests to different servers of an Access Server cluster. This is only needed for the ADMIN interface.

Please that this API is still in development and stability is not guaranteed. API endpoints and parameters can change without notice.

Also note that while great care has been taken that this API documentation matches the implementation, some differences to the implemented API can exist as well.

Viewing this API documentation in swagger via https://access-server.examples.com/api/docs can be enabled by using setting the configuration variable openapi.web_access to 1 e.g. by using

or setting the variable via the admin UI configuration editor.

For more information about the API of OpenVPN Access Server see also https://openvpn.net/static-links/documentation-access-server-web-api

Base URLs:

/api
https://access-server.example.com/api/

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

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

Default

servers__saml_acs

Responses

Status	Meaning	Description	Schema

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

servers__saml_metadata

Responses

Status	Meaning	Description	Schema

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

servers__saml_redirect

Responses

Status	Meaning	Description	Schema

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

servers__openvpn-api_profile

Responses

Status	Meaning	Description	Schema

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

servers__GetInstallerViaToken

Responses

Status	Meaning	Description	Schema

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

servers__GetProfileViaToken

Responses

Status	Meaning	Description	Schema

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

servers__GetAutologin

Responses

Status	Meaning	Description	Schema

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

servers__GetUserlogin

Responses

Status	Meaning	Description	Schema

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

servers__GetGeneric

Responses

Status	Meaning	Description	Schema

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

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.

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	errorReason

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/saml/acs',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/saml/metadata',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

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

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

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

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/GetInstallerViaToken',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/GetProfileViaToken',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/GetAutologin',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/GetUserlogin',
{
  method: 'SERVERS',

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

Request

const headers = {
  'X-OpenVPN-As-AuthToken':'API_KEY'
};

fetch('/api/GetGeneric',
{
  method: 'SERVERS',

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

Request

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

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

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

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

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

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

changePasswordLocalUser

POST /auth/password/change

Allows to change a local password. Note to verify that the user knows the old password, this needs to be used with an auth token that has been obtained very recently (or auth token issued to an admin user). This operation will only allow admin auth token or very recently issued user auth token to ensure that the user knows the old password. The consumer of this API will need to issue a new user token as part of flow to use the API. By very recent we mean very recent is a small time period like 30s.

Body parameter

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

enrollUserMFA

POST /auth/mfa/enroll

enrolls a user into MFA by providing a valid MFA token. After the enrollment auth token that has been generated on the first MFA stage can be used as a regular one. This also provides a fully authenticated auth-token as response that can be used without having to login again and going through the MFA process if no target user was provided to the API. Otherwise only the username will be returned. This internally will set the totp_locked (pvt_google_auth_secret_locked) if successful.

Body parameter

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

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

Request

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

Response

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

Request

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

Response

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

Request

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

Response

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

Request

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

Response

json

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

Request

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

Response

json

{
  "detail": "string"
}

Request

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

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

Response

json

{
  "user_properties": {
    "requires_mfa_enrollment": true,
    "user_type": "admin",
    "mfa_secret": "string",
    "allowed_profiles": [
      "autologin"
    ],
    "enforce_strong_passwords": true,
    "allow_password_change": true
  },
  "username": "string",
  "auth_token": "string",
  "expires_after": "string",
  "renewable_until": "string"
}

client-import-api

The endpoints which are used on OpenVPN Access Server to import profiles into OpenVPN clients

get__GetInstallerViaToken

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

get__GetProfileViaToken

GET /GetProfileViaToken

This endpoint is one of endpoints of Web Services API called REST - the api, that supports to fetch client configuration file from Access server. Note that it is different from webapi/v1/api endpoints from that perspective that it still accepts any HTTPS client tool in usage, but unlike Client Web Service, it does not support full UI/UX design for Access Server. However Web Services API REST may respond with minimal html page. Some endpoints of this API require authentication as string-token, like this endpoint, in particular. See more about token in ProfileDownloadToken schema description.

Responses

Status	Meaning	Description	Schema
200	OK	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

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

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

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

Request

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

Request

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

Response

xml

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

Request

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

Response

xml

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

Request

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

Response

xml

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

Request

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

Response

xml

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

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

Request

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

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

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

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

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

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

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

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.

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

enumerateTokenIds

standard response when there insufficient rights to use an 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

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

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

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

Request

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

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

Request

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

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

Request

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

Response

json

{
  "total": 0,
  "profiles": [
    {
      "serial": "1708464983752887'",
      "common_name": "OpenVPN VPN server CA",
      "algorithm": "rsa2048",
      "not_before": "2020-03-27",
      "not_after": "2030-03-26",
      "self_signed": true,
      "signing_ca": "123",
      "signing_ca_cn": "RootCA",
      "device_id": "string",
      "comment": "My toaster running Doom",
      "profile_type": "autologin",
      "tls_crypt_v2": true,
      "last_used": "2019-08-24",
      "username": "string"
    }
  ]
}

Request

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

Request

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

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

Request

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

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

Response

json

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

Request

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

Response

json

{
  "message": "string"
}

Request

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

Response

json

{
  "message": "string"
}

Request

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

Response

json

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

vpnca

endpoints that manage the CA(s) that is used to sign the VPN server certificate and the client certificates

getVPNCas

standard response when there insufficient rights to use an 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

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.

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

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

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.

CaSupportedAlgorithms

standard response when there insufficient rights to use an 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

Request

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

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

Response

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

Request

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

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

Response

json

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

Request

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

Response

json

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

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

Request

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

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

Response

json

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

info

endpoints that allow to query various aspects of the running server and its status

certificateInfo

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

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.

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

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

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.

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.

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

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

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

get__vpn_dco-module

standard response when there insufficient rights to use an 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

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

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.

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

Request

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

Response

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
}

Request

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

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

Response

json

{
  "status": true
}

Request

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

Response

json

{
  "chain": [
    {
      "serial": "1708464983752887'",
      "common_name": "OpenVPN VPN server CA",
      "algorithm": "rsa2048",
      "not_before": "2020-03-27",
      "not_after": "2030-03-26",
      "self_signed": true,
      "signing_ca": "123",
      "signing_ca_cn": "RootCA",
      "sha256fp": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
      "subj_alt_names": [],
      "subject": [],
      "ca": true
    }
  ]
}

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

Request

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

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

Response

json

{
  "eula": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
  "eula_web": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...",
  "eula_version_as": 7,
  "eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
  "eula_accepted": true
}

Request

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

Response

json

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

Request

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

Response

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

Request

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

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

Response

json

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

Request

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

Response

json

{
  "configuration_items": {
    "total": 0,
    "items": [
      {}
    ]
  },
  "server_info": {
    "version": "2.13.0-internal",
    "build": "18eba991",
    "web_version": "2.12.7-82fda2",
    "web_override": true,
    "client_version": [
      "27"
    ],
    "os_distribution": "Ubuntu 24.04.6 LTS",
    "architecture": "arm64",
    "cores": 0,
    "os_hostname": "access-server-os-hostname"
  },
  "dco_module": {
    "available": true,
    "version": "0.2.20230323"
  },
  "eula_status": {
    "eula_version_as": 7,
    "eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
    "eula_accepted": true
  }
}

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

license

APIs that allow examining and setting licensing of the AS instance

licenseInfo

standard response when there insufficient rights to use an 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

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.

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

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.

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

deactivateSubscription

standard response when there insufficient rights to use an 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

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.

standard response when there insufficient rights to use an 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

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.

standard response when there insufficient rights to use an 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

licenseGetMachineId

standard response when there insufficient rights to use an 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

Request

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

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

Response

json

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

Request

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

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

Response

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

Request

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

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

Response

json

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

Request

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

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

Request

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

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

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

Request

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

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

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

Request

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

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

Response

"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

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.

Request

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

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.

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

rrdnshostname

standard response when there insufficient rights to use an 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

clustergetprops

standard response when there insufficient rights to use an 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

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

standard response when there insufficient rights to use an 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

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.

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

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

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeJoinRequest clusterNodeJoinRequest	false	none

standard response when there insufficient rights to use an 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

Parameters

Name	In	Type	Required	Description
body	body	clusterNodeCreateRequest clusterNodeCreateRequest	false	none

standard response when there insufficient rights to use an API.

post__cluster_leave

standard response when there insufficient rights to use an 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

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

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.

Request

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

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

Response

json

{
  "nodes": {
    "property1": {
      "name": "vienna.example.com",
      "api_endpoint": "https://node1:945",
      "certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
      "restart_pending": true
    },
    "property2": {
      "name": "vienna.example.com",
      "api_endpoint": "https://node1:945",
      "certificate_fingerprint": "36:D7:D5:1F:47:4A:84:A2:A3:0A:41:BC:92:CB:A5:D9:D6:5F:75:64:84:01:1D:6F:58:B9:D6:67:F8:DB:BE:9C",
      "restart_pending": true
    }
  }
}

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

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

Request

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

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

Response

json

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

Request

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

Response

json

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

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

Request

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

Response

json

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

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

Request

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

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

Response

json

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

Request

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

Response

json

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

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

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

Parameters

Name	In	Type	Required	Description
restartMode	query	restartMode 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

Request

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

Response

"string"

Request

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

Request

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

Response

json

{
  "last_restarted": "2019-08-24T14:15:22Z",
  "service_status": {
    "property1": {
      "status": "on",
      "error": []
    },
    "property2": {
      "status": "on",
      "error": []
    }
  },
  "auth_module_status": {
    "property1": "on",
    "property2": "on"
  }
}

configurationProfile

API to manage OpenVPN Access Server’s main configuration database

enumerateConfigurationProfileList

standard response when there insufficient rights to use an 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

configurationProfileDelete

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an 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

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.

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

validateConfigProfile

Parameters

Name	In	Type	Required	Description
profile	path	configurationProfile	true	none

standard response when there insufficient rights to use an 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

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.

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

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.

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

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

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.

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

Request

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

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

Response

json

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

Request

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

Response

json

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

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

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.

Throw validation error if wrong request passed

Only POST for this url is allowed. Throw unsupported error if method is not POST

Response Schema

This operation does not require authentication

get__saml_metadata

SAML is not configured or invalid configuration

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

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

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

Parameters

Name	In	Type	Required	Description
relay_state	query	string	false	If not set, the cws relay_state is assumed

Request

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

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

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

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

Request

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

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

Request

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

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

Request

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

Response

json

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

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

get__vpn_status

standard response when there insufficient rights to use an API.

Responses

Status	Meaning	Description	Schema
200	OK	Vpn Server status	Inline
403	Forbidden	only admin users are allowed to use this API	errorReason

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.

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

Request

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

Response

json

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

Request

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

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

Response

json

{
  "vpn_clients": [
    {
      "daemon_id": "openvpn_7",
      "client_id": 7,
      "bytes_sent": 0,
      "bytes_received": 0,
      "commonname": "plato_AUTOLOGIN",
      "username": "plato",
      "connected_since": "2019-08-24T14:15:22Z",
      "datachannel_cipher": "ChaCha20-Poly1305",
      "real_address": "1.2.7.8:23123",
      "virtual_ipv4_address": "10.0.0.7",
      "virtual_ipv6_address": "fd00:f00f::b00f"
    }
  ],
  "vpn_daemons": {
    "property1": {
      "dco": true,
      "version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
    },
    "property2": {
      "dco": true,
      "version": "OpenVPN 2.7_git [git:bloom/520bc001b093857c+] x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZ4] [EPOLL] [MH/PKTINFO] [AEAD] [DCO] built on Nov 30 2023"
    }
  }
}

Request

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

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

Response

json

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

cws

cws stands for client website. These APIs are the ones that can be used as normal users and do not require admin permission for basic operations. Some have extended functionality that require admin privileges like acting on the behalf of another user.

generateInstallerUrl

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

Request

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.

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

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.

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

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.

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

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.

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

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.

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

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

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

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

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

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.

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

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.

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.

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

Request

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

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

Response

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

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

Response

json

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

Request

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

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

Request

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

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

Request

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

Response

json

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

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

Request

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

Response

json

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

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

Request

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

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

Response

json

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

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.

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

Request

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

Response

json

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

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

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

Parameters

Name	In	Type	Required	Description
body	body	certificateCreateRequest certificateCreateRequest	false	none

standard response when there insufficient rights to use an 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

Request

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

Response

json

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

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

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.

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

Request

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

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

Response

json

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

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.

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

Request

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

Response

json

{
  "totp_secret": "string"
}

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

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.

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

Request

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

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

Response

json

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

getCWSconfig

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	WebsiteConfig

This operation does not require authentication

Request

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

Response

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
}

Request

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

Response

json

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

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.

post__server_failover-init

POST /server/failover-init

initialises the failover configuration for the secondary node. The configuration should be first validated by the /server/failover-test API call. If no old configuration exists use the new configuration for both old and new configuration. After this call has successfully finished, a /server/restart with systemctl needs to be called (with a delay of 10s or similar). In order for failover to properly work, the webserver certificates should be moved to the config DB and not referenced by their filename.

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

Parameters

Name	In	Type	Required	Description
body	body	any	false	none

standard response when there insufficient rights to use an API.

Request

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

Response

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

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

Request

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

Response

json

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

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

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

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

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.

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

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

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

groupSorting

specifies by which attribute groups should be sorted

Properties

None

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

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

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

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

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.

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.

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

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.

certificateCommonName

The common name of the certificate.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string,null	false	none	The common name of the certificate.

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

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

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

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

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

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.

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

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.

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

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

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.

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

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

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.

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

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.

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

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.

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

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

booleanConfigurationValue

Properties

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

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

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

configurationItemKey

the configuration value’s key.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the configuration value’s key.

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

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

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

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.

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.

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

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

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.

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

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

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

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

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

unlicensedInfo

(dummy) information when AS is not currently licensed

Properties

None

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.

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

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

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

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

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.

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

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.

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)

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)

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.

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.

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

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

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)
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 userPropValue	false	none	This object describes a single user property value. If it is
deny_web	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
admin	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
autologin	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
auth_method	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cc_commands	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
totp	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
password_strength	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
allow_password_change	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
reroute_gw	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
allow_generate_profiles	userPropValue 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.

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.

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 userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_win_user_disconnect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_win_admin_connect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_win_admin_disconnect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_user_connect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_user_disconnect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_admin_connect	userPropValue userPropValue	false	none	This object describes a single user property value. If it is
cli_script_connect_mac_admin_disconnect	userPropValue 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 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 userPropValue	false	none	This object describes a single user property value. If it is

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

serviceStatusEnum

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	on
anonymous	disabled
anonymous	error
anonymous	enabled

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

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

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

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

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.

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

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

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

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

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

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.

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.

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.

mysqluri

the URI of the mysql server.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	the URI of the mysql server.

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.

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

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

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.

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

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.

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

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

filterTimeOrDuration

This specifies that the result should be filtered by this attribute with the specified time range. If one of the time points is missing it means that the range is unspecified. E.g. a start of 2020-02-02 and no end point means the time interval of [2020-02-02, ∞). Same with relative time for start and end.

Properties

Name	Type	Required	Restrictions	Description
start	string(date-time)	false	none	none
end	string(date-time)	false	none	none
start_relative	string	false	none	none
end_relative	string	false	none	none

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

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

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

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

filterTime

Properties

Name	Type	Required	Restrictions	Description
start	string(date)	false	none	none
end	string(date)	false	none	none

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

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

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.

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

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.

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.

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.

IpService

describes an IP UDP/TCP service or an icmp service

Properties

oneOf

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

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

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)

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

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

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

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]

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

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.

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

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

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

json

"autologin"

json

"niccolo@paganini.it"

json

"string"

json

"win_v3"

json

"serial"

json

"admin"

json

"name"

json

"node"

json

"asc"

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

json

"admin"

json

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

json

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

json

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

json

"1708464983752887'"

json

"OpenVPN VPN server CA"

json

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

json

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

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

json

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

json

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

json

"Client disconnected for administrative reasons"

json

"John should not be working after hours"

json

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

json

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

json

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

json

"string"

json

"rsa2048"

json

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

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
}

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
}

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

json

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

json

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

json

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

json

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

json

{
  "value": "string"
}

json

"default"

json

"vpn.server.cipher"

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
}

json

"string"

json

"string"

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"

json

"https://node1:945"

json

"cold"

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

json

"openvpn_7"

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

json

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

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

json

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

json

{}

json

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

json

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

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

json

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

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

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

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

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

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

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

json

{
  "def_deny": true
}

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

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

json

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

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

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

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

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

json

"on"

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

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

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

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

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
}

json

"none"

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

json

{
  "eula_version_as": 7,
  "eula_web_hash": "36D7D51F474A84A2A30A41BC92CBA5D9D65F756484011D6F58B9D667F8DBBE9C",
  "eula_accepted": true
}

json

{
  "notification_type": "CLUSTER_RESTART_PENDING"
}

json

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

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

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

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
}

json

"mysql://user:password@mysql.example.com:3306/"

json

{
  "user": "niccolo@paganini.it",
  "profile_type": "autologin",
  "tls_crypt_v2": true,
  "comment": "connected from my iPhone",
  "ignore_missing_user": null
}

json

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

json

{
  "page_size": 0,
  "offset": 0,
  "sort_by": "asc"
}

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

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

json

{
  "admin": {
    "value": true
  },
  "autologin": {
    "value": true
  },
  "anywhere": {
    "value": "bass",
    "fields": [
      "username",
      "group"
    ]
  }
}

json

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

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

json

{
  "start_relative": "20d",
  "end_relative": "15d 20m"
}

json

{
  "value": "20kb",
  "operation": "less_than"
}

json

{
  "operation": "substring",
  "value": "vio"
}

json

{
  "value": "20d",
  "operation": "less_than"
}

json

{
  "value": 400,
  "operation": "less_than"
}

json

{
  "start": "2019-08-24",
  "end": "2019-08-24"
}

json

{
  "value": true
}

json

{
  "value": "bass",
  "fields": [
    "username",
    "group"
  ]
}

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

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

json

true

json

[
  "string"
]

json

{
  "ip": "123.7.3.1",
  "start_port": 7000,
  "end_port": 7111,
  "protocol": "udp"
}

json

{
  "protocol": "tcp",
  "start_port": 0,
  "end_port": 0
}

json

{
  "protocol": "tcp",
  "type": "icmp-any"
}

json

{
  "protocol": "tcp",
  "start_port": 0,
  "end_port": 0
}

json

"tcp"

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

json

{
  "type": "user",
  "accept": true,
  "username": "niccolo@paganini.it",
  "groupname": "string",
  "subnet": {
    "prefix_length": 21,
    "netip": "131.234.72.0",
    "ipv6": false,
    "service": [
      {}
    ]
  }
}

json

{
  "prefix_length": 21,
  "netip": "131.234.72.0",
  "ipv6": false,
  "service": [
    {
      "protocol": "tcp",
      "start_port": 0,
      "end_port": 0
    }
  ]
}

json

{
  "prefix_length": 21,
  "netip": "131.234.72.0",
  "ipv6": false
}

json

{
  "ipv6": true,
  "first_ip": "fd00::18cc:1b01:a772:50e1",
  "last_ip": "fd00::18cc:1b01:a772:80e1"
}

json

{
  "friendly": "string",
  "status": true,
  "message": "string"
}

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

Abstract

The Access Server REST API allows programmatic download of OpenVPN connection profiles.

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.

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

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

Important

Ensure the user has autologin permission enabled in the Admin Web UI under User Permissions.

Success response

Content-Type: application/x-openvpn-profile

Error response

Content-Type: text/xml

Request

curl -u 'username:password' "https://<ACCESS_SERVER>/rest/GetUserlogin?tls-cryptv2=1&action=import"

Request

curl -u 'username:password' https://<ACCESS_SERVER>/rest/GetAutologin

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

Example 2. 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 3. 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.

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

Caution

While you can disable web server certificate verification using the -k option, we discourage this practice for security reasons.

Error Handling

The REST API will return errors in an XML format (in contrast to typical REST JSON responses). These are some common error responses:

Authentication failed (invalid username/password):

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