Admin Management API

About 5 min

Datawiza Admin API

The Datawiza Admin API is the primary way that apps and services interact with Datawiza. You can use it to implement functions such as programmatically managing your Datawiza objects.

Design Principles

URL Namespace

All URLs listed in the documentation should be preceded by the Datawiza domain https://console.datawiza.com.

Note: All API requests must use the HTTPS scheme.

Versioning

The Datawiza API is a versioned API. Datawiza reserves the right to add new parameters, properties, or objects to the API without advance notice. These updates are considered non-breaking, and the compatibility rules below should be followed to ensure your app doesn't break. Breaking changes such as removing or renaming a property will be released as a new version of the API. Datawiza will provide a migration path for new versions of APIs and will communicate timelines for end-of-life when deprecating APIs.

The API version is included in the path. For example, the Applications API is currently at version v1:

https://console.datawiza.com/admin/api/v1/applications

Don't consume any Datawiza API unless it's documented on this site. All undocumented endpoints should be considered private, subject to change without notice, and not covered by any agreements.

Compatibility Rules for Input Parameters

Requests are compatible irrespective of the order in which the query parameters appear.
Requests are compatible irrespective of the order in which the properties of the JSON parameters appear.
New query parameters may be added to future versions of requests.
Existing query parameters can't be removed from future versions of requests.
Existing properties can't be removed from the JSON parameters in future versions of requests.

Compatibility Rules for JSON Responses

Responses are compatible irrespective of the order in which the properties appear.
New properties may be added to future versions of the response.
Existing properties can't be removed from future versions of the response.
Properties with null values may be omitted by responses.

Media Types

Note: JSON responses, including errors, may contain user input. To help prevent potential cross-site scripting attacks, make sure to properly escape all values before use in a browser or any HTML context.

The API currently supports only JSON as an exchange format. Be sure to set both the Content-Type and Accept headers for every request as application/json.

All Date objects are returned in unix timestamp in milliseconds.

Character Sets

Datawiza supports a subset of the UTF-8 specification. Specifically, any character that can be encoded in three bytes or less is supported. BMP characters and supplementary characters that must be encoded using four bytes aren't supported at this time.

HTTP Verbs

Where possible, the Datawiza API strives to use appropriate HTTP verbs for each action.

Verb	Usage
`GET`	Used for retrieving objects.
`PATCH`	Used for partially updating objects. Note: Not all APIs implement PATCH for updates.
`POST`	Used for creating objects or performing custom actions (such as searching under conditions).
`PUT`	Used for replacing objects or collections.
`DELETE`	Used for deleting objects.

Response Format

Responses are formatted as a JSON object.

Successful responses will have an errMsg value of "OK", an errCode value of 0, and a data key. The data will either be a single object or a sequence of other JSON types, depending on which endpoint is called. All successful requests return a 200 status if there's content to return or a 204 status if there's no content to return.

Values are returned as strings unless otherwise documented.

Example successful response:

{
  "errCode": 0,
  "errMsg": "OK",
  "data": {
    "key": "value"
  }
}

Errors

Note: JSON responses, including errors, may contain user input. To help prevent potential cross-site scripting attacks, ensure to properly escape all values before use in a browser or any HTML context.

All requests that result in an error return the appropriate 4xx or 5xx error code with a custom JSON error object:

errCode: A code that is associated with this error type.
errMsg: A natural language explanation of the error.

Example error response:

{
  "errCode": "3002",
  "errMsg": "Api validation failed"
}

Note: Only the errCode property is supported for runtime error flow control. The errMsg property is only intended for troubleshooting and may change over time.

Authentication

Note: Only administrators can create or modify an Admin API token in the Datawiza Management Console.

Sign up for a Datawiza account if you aren't already a customer. Currently, you can only use Admin APIs when you are under a premium plan.
Log in to the Datawiza Admin Panel and navigate to Api Tokens.
Go to the Admin Tokens page and then click the Create button.
Give a descriptive name for the admin token.
Note down the token value. It will only appear once.
Don't share it with unauthorized individuals or email it to anyone under any circumstances.

Pagination

Pagination is the technique used to divide large datasets into smaller, manageable chunks. Instead of returning thousands of records at once, results are broken up using two parameters: page and size.

The size parameter determines how many records to return in a single request. The page parameter tells which slice of the data you want. For example, if the size is 10 and you request page 2, you will receive records 11 through 20.

Note: For technical reasons, not all APIs respect pagination or the page and size parameters.

Param	Description
`page`	The cursor that points to the start of the page of data that has been returned.
`size`	The number of individual objects that are returned in each page.

Response Codes

The HTTP response code will be the first three digits of the more specific code found inside the JSON object. Each endpoint's documentation lists the HTTP response codes it can return.

Additionally, all API endpoints that require a signed request can return the following HTTP response codes:

Code	Meaning
`200`	The request completed successfully.
`401`	The `Authorization`, `Date`, and/or `Content-Type` headers were missing or invalid.
`403`	This integration is not authorized for this endpoint.
`405`	The request's HTTP verb is not valid for this endpoint (for example, POST when only GET is supported).
`429`	The account has made too many requests of this type recently. Try again later.

API Details

List All Applications

Lists all apps in the org with pagination. A subset of apps can be returned if you search by name. The results are paginated according to the page and size parameters.

Request

curl --location 'https://console.datawiza.com/admin/api/v1/applications/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "page": 0,
  "size": 20,
  "name": "my-app"
}'

Query Parameters

Name	Required	Type	Position
`page`	Required	number	JSON body
`size`	Required	number	JSON body
`name`	Optional	string	JSON body

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "data": [
    {
      "id": "68496c6bd01242b98e2f469eaa2f3465",
      "creationDate": 1763784795450,
      "lastUpdateDate": 1772771754747,
      "deploymentId": "b12d23bd8cfa4f929dbc3257b6cfb78a",
      "name": "TEST MFA RULE",
      "platform": "WEB",
      "publicDomain": "https://jde.example.com",
      "listenPort": 443,
      "upstreams": [],
      "upstreamSwitch": "DUMMY",
      "specialApp": {},
      "profileSelect": null,
      "enabled": true
    },
    {
      "id": "d1f23a6f395045dabc2967cb300eb749",
      "creationDate": 1749568335854,
      "lastUpdateDate": 1772685268009,
      "deploymentId": "29c0e17183d4426595d72fedd13922a2",
      "name": "aaaa2222",
      "platform": "WEB",
      "publicDomain": "https://header.datawiza.net",
      "listenPort": 443,
      "upstreams": [],
      "upstreamSwitch": "DUMMY",
      "specialApp": {},
      "profileSelect": null,
      "enabled": true
    }
  ],
  "pageSize": 20,
  "pageNum": 1,
  "totalPage": 1,
  "totalElements": 2,
  "errCode": 0,
  "errMsg": "OK"
}

Response Paging

A successful response when the total results exceed the endpoint's default page size will include paging metadata. If the request returns no paging metadata, then either the endpoint does not support paged results or the total results do not exceed one page.

Metadata	Description
`totalElements`	An integer indicating the total number of objects retrieved by the API request across all pages of results.
`totalPage`	An integer indicating the total number of pages retrieved.
`pageNum`	The current returned page number.
`pageSize`	The current returned page size.

Get the SSL of an Application

Returns the SSL status of an application. You will need to provide the application ID in the request URL.

Request

curl --location --request GET \
  'https://console.datawiza.com/admin/api/v1/applications/68496c6bd01242b98e2f469eaa2f3465/ssl' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "data": {
    "id": "1e16b017e823458b97a9af15c5c5f6d9",
    "creationDate": 1763784795669,
    "lastUpdateDate": 1763784795669,
    "isSSL": true,
    "mode": "SELF_SIGNED"
  },
  "errCode": 0,
  "errMsg": "OK"
}

SSL Properties

Property	Type	Description
`isSSL`	boolean	Indicates if SSL is turned on or not.
`mode`	enum	`SELF_SIGN` means DAP is going to use a Datawiza self-signed certificate. `UPLOAD` means DAP is going to use a customer-uploaded certificate.
`subject`	string	The subject of the certificate.
`fingerPrint`	string	The fingerprint of the certificate.
`expirationTime`	timestamp	The expiration time of the certificate.

Update the SSL of an Application

Updates the SSL properties of an application.

Query Parameters

Name	Required	Type	Position
`isSSL`	Required	boolean	multipart/form-data
`mode`	Required if `isSSL` is true	enum	multipart/form-data
`uploadFile`	Required if `mode` is `UPLOAD`	boolean (must be `false`)	multipart/form-data
`cert`	Required if `mode` is `UPLOAD`	string	multipart/form-data
`key`	Required if `mode` is `UPLOAD`	string	multipart/form-data

Request

curl --location \
  'https://console.datawiza.com/admin/api/v1/applications/{{application-id}}/ssl' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'isSSL="true"' \
  --form 'mode="UPLOAD"' \
  --form 'uploadFile="false"' \
  --form 'cert="-----BEGIN CERTIFICATE-----
......
-----END CERTIFICATE-----"' \
  --form 'key="-----BEGIN PRIVATE KEY-----
......
-----END PRIVATE KEY-----"'

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "errCode": 0,
  "errMsg": "OK"
}