API Settings

The AD360 REST APIs facilitate sharing of data between AD360 and any third-party application or web service; they allow you to manage the various settings available in AD360, such as domain settings, proxy server settings, and email server settings. These APIs can be leveraged from any application capable of making HTTP requests.

Available APIs

The following list contains AD360 APIs currently available, as well as their functions:

API Function
Get Domain Settings  Read the details of the domains configured in AD360.
Update Domain Credential Add/modify the domain credential configured in AD360.
Get Proxy Settings  Read the proxy server settings configured in AD360.
Update Proxy Settings Add/modify the proxy server settings configured in AD360.
Get Mail Server Settings Read the mail server settings configured in AD360.
Update Mail Server Settings Add/modify the mail server settings configured in AD360.

Note: Only JSON requests (Content-Type: application/x-www-form-urlencoded) and responses (Content-Type: application/json) are supported.

How do I access AD360's APIs?

To access AD360's APIs, you first need to create an AuthToken. Follow the steps below:

  1. Log in to AD360 as an admin.
  2. Go to Admin → General Settings → API Settings.

    ad360-api-settings

  3. Click Create New AuthToken.
  4. Select the scopes that you want to access by clicking on the + symbol.

    What is scope?
    Scope defines what APIs can be accessed using an AuthToken. One or a group of APIs can be part of a scope.

  5. Next, choose an expiration date for the AuthToken.
  6. Click Create.

    create-auth-token

  7. Your AuthToken will be created.

    Note: Copy this AuthToken and keep it safe for further use. If lost, it cannot be retrieved and must be regenerated.

API usage

To access an AD360 API, use the URL format below:

<scheme:port[/context]>/RestAPI/*.*[?query][#fragment]

Example: http://ad360-server:8082/RestAPI/DomainSettings/getDomains

Authorization: Bearer <authtoken>

Managing the AuthTokens

You can find all the AuthTokens you’ve created under the API Settings page in AD360. From here, you can see various details of the AuthTokens, such as their expiration date, scope, created date, and last accessed time. You can also revoke an AuthToken to disable it completely. Follow the steps below to manage AuthTokens:

  1. Log in to AD360 as an admin.
  2. Go to Admin → General Settings → API Settings. You’ll see a table containing all the AuthTokens you’ve created.
  3. To filter the AuthTokens: From the Showing drop down, you can select whether you want to view all the AuthTokens or only the AuthTokens that are active, expired, or revoked.
  4. To view the scopes of an AuthToken: Click under the Scope column to view all the scopes that an AuthToken provides access to.
  5. To audit AuthToken access: Hover the mouse over the values in the Last Accessed Time column. An audit icon will appear. Click it to view a detailed audit trail of who accessed the AuthToken.
  6. To revoke an AuthToken: Hover the mouse in the open space next to Last Accessed Time column. A Revoke link will appear. Click it to revoke the AuthToken.

    7. Note:  Once an AuthToken is revoked, the APIs that depend on it will no longer work.

Get Domain Settings API

This API allows you to get details of the domains configured in AD360.

  • Request URL: http://<ad360-server>: <port>/RestAPI/DomainSettings/getDomains
  • HTTP Method: GET
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    Nil - No parameters required
  • Response Parameters:
    Parameter Mandatory Description
    DEFAULT_NAMING_CONTEXT Yes Represents default naming context of the domain.
    IS_DEFAULT_DOMAIN Yes Represents whether the domain is used as a default domain in the login page.
    DC_LIST Yes Lists the domain controllers of the domain.
    DOMAIN_FLAT_NAME Yes Shows the domain flat name of the domain.
    DOMAIN_NAME Yes Shows the domain name.
    DOMAIN_DNS_NAME Yes Shows the DNS name of the domain.
    USER_NAME No Shows the username of the account used to configure the domain in AD360.
    DOMAIN_FUNCTIONAL_LEVEL Yes Shows the domain functional level of the domain.
    IS_AUTHENTICATION_REQUIRED No Represents whether authentication details were provided when the domain was configured.
    IS_LDAP_SSL_ENABLED No Represents whether the connection between the domain and AD360 is LDAPS-enabled.
    STATUS_MESSAGE No Shows the result of the previous domain configuration operation.

Sample request:

http://ad360-dc1:8082/RestAPI/DomainSettings/getDomains

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

Sample response:

[{"DEFAULT_NAMING_CONTEXT":"DC=ad360,DC=local","IS_DEFAULT_DOMAIN":"true","DC_LIST":["win2k12master.ad360.local","EST-ADC.ad360.local"],"DOMAIN_FLAT_NAME":"AD360","DOMAIN_NAME":"ad360.local","DOMAIN_DNS_NAME":"ad360.local","DOMAIN_FUNCTIONAL_LEVEL":"Windows Server 2008"}]

Update Domain Settings API

This API allows you to update the domain settings in AD360.

  • Request URL: http://<ad360-server>:<port>/RestAPI/DomainSettings/updateDomainCredential
  • HTTP Method: POST
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    DOMAINS Yes Must have JSON input, with the following attributes (Key-Value Pair)
    Attributes Mandatory Description
    DOMAIN_NAME Yes Represents the domain name.
    USER_NAME No A valid username for authentication.
    USER_PASSWORD No A valid password for authentication.
  • Response Parameters:
    Parameter Mandatory Description
    STATUS Yes Shows the status of the overall request (e.g. success or failure).
    DOMAINS Yes Shows the status of the request for each domain.

Sample request:

http://ad360-dc1:8082/RestAPI/DomainSettings/updateDomainCredential

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

DOMAINS=[{"DOMAIN_NAME":"ad360.local","USER_NAME":"admin","USER_PASSWORD":"Test123"}]

Sample response:

{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"SUCCESS\"}"}}

  • Error Responses:
    INVALID_DOMAIN Example:{"STATUS":"SUCCESS","DOMAINS":{"--":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"INVALID_DOMAIN\"}"}}
    DOMAIN_NOT_AVAILABLE Example:{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"INVALID_OR_INSUFFICIENT_CREDENTIAL\"}"}}
    INVALID_OR_INSUFFICIENT_CREDENTIAL
    FAILURE_IN_SERVER Example:{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"FAILURE_IN_SERVER\"}"}}

    {"STATUS":"FAILURE","ERROR_MSG":"FAILURE_IN_SERVER"}

Get Proxy Settings API

This API allows you to get the details of the proxy server configured in AD360.

  • Request URL: http://<ad360-server>:<port>/RestAPI/ProxySettings/getSettings
  • HTTP Method: GET
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    Nil No parameters required.
  • Response Parameters:
    Parameter Mandatory Description
    ENABLE_PROXY Yes Enable or disable proxy server.
    SERVER_NAME No Host name or IP address of the proxy server.
    PORT No Port number of the proxy server.
    USER_NAME No Username used for proxy server authentication.

Sample request:

http://ad360-dc1:8082/RestAPI/ProxySettings/getSettings

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

Sample response:

{"ENABLE_PROXY":"true","SERVER_NAME":"ad360-dc1","PORT":"5005","USER_NAME":"admin"}

Update Proxy Settings API

This API allows you to update the proxy settings in AD360.

  • Request URL: http://<ad360-server>:<port>/RestAPI/ProxySettings/updateSettings
  • HTTP Method: POST
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    PROXY_SETTINGS Yes Must have JSON input with the following attributes (Key-Value Pair).
    Attributes Mandatory Description
    ENABLE_PROXY Yes Enable or disable proxy server.
    SERVER_NAME Yes Server name or IP address of the proxy server.
    PORT Yes Enable or disable proxy server.
    USER_NAME No Username used for proxy server authentication.
    PASSWORD No Password used for proxy server authentication.
  • Response Parameters:
    Parameter Mandatory Description
    STATUS Yes Shows the status of the request (e.g. success or failure).

Sample request:

http://ad360-dc1:8082/RestAPI/ProxySettings/updateSettings

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

PROXY_SETTINGS={"ENABLE_PROXY":"true","SERVER_NAME":"ad360-dc1","PORT":"5005","USER_NAME":"admin","PASSWORD":"Test123"}

Sample response:

{"STATUS": "SUCCESS"}

  • Error Responses:

    PS001 - Authentication required to access proxy server.

    PS002 - Proxy Server is down. Please try again later.

    PS003 - Failed to save the proxy settings.

Get Mail Settings API

This API allows you to get the details of the mail server configured in AD360.

  • Request URL: http://<ad360-server>:<port>/RestAPI/MailSettings/getSettings
  • HTTP Method: GET
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    Nil - No parameters required.
  • Response Parameters:
    Parameter Mandatory Description
    SERVER_NAME Yes Represents the host name or IP address of the mail server.
    PORT Yes Port number of the mail server.
    FROM_MAIL_ID Yes Represents the email address used for sending notification emails.
    ADMIN_MAIL_ID Yes Represents the comma-separated list of email addresses to which the notification emails will be sent.
    USER_NAME No Username used for mail server authentication.
    CONNECTION_SECURITY Yes Represents secure connection type (SSL or TLS).

Sample request:

http://ad360-dc1:8082/RestAPI/MailSettings/getSettings

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

Sample response:

{"PORT":"25","FROM_MAIL_ID":"no-reply@ad360.local","SERVER_NAME":"smtp","USER_NAME":"admin","ADMIN_MAIL_ID":"admin@ad360.local,super-admin@ad360.local"}

Update Mail Settings API

This API allows you to update the mail server settings in AD360.

  • Request URL: http://<ad360-server>:<PORT>/RestAPI/MailSettings/updateSettings
  • HTTP Method: POST
  • Authorization: Bearer <authtoken>
  • Request Parameters:
    Parameter Mandatory Description
    MAIL_SETTINGS Yes Must have JSON input with the following attributes (Key-Value Pair)
    Attributes Mandatory Description
    SERVER_NAME Yes Server name or IP address of the mail server.
    PORT Yes Port number of the mail server
    FROM_MAIL_ID Yes The email address from which notifications will be sent.
    ADMIN_MAIL_ID Yes List of recipients.
    USER_NAME No Username used for mail server authentication.
    PASSWORD No Password used for mail server authentication.
    CONNECTION_SECURITY Yes Accepted values are SSL or TLS.
  • Response Parameters:
    Parameter Mandatory Description
    STATUS Yes Shows the status of the request (e.g. success or failure).

Sample request:

http://ad360-dc1:8082/RestAPI/MailSettings/updateSettings

Authorization: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

MAIL_SETTINGS={"PORT":"25","FROM_MAIL_ID":"no-reply@ad360.local","SERVER_NAME":"smtp","USER_NAME":"admin","ADMIN_MAIL_ID":"admin@ad360.local","PASSWORD":"Test123"}

Sample response:

{"STATUS": "SUCCESS"}

  • Error Responses:

    MS001 - Invalid from email address.

    MS002 - Invalid admin email address.

    MS003 - Invalid email address, or mail server requires authentication.

    MS004 - Please check whether the server name/IP, port number, and connection type are correct, and try again.

    MS005 - Network failure, or mail server is down.

    MS006 - Authentication details for mail server are incorrect.

    MS007 - Unrecognized SSL message: Secure Connection enabled.

    MS008 - Invalid domain name.

    MS009 - Please make sure the mail address doesn't contain "zohocorp" domain.

    MS010 - Invalid server name or port number.

    MS011 - Invalid username or password.

    MS012 - Unable to configure SMTP server with TLS enabled.

    MS013 - Invalid connection type. Connection type should be SSL or TLS.

    MS014 - Invalid port number.

Common error response codes

AT001 - Invalid or missing AuthToken. Check whether the AuthToken is not revoked or expired.
AT002 - The given AuthToken doesn't have necessary permission to access the requested API.
AT003 - The requested API doesn't support this HTTP Method.
AT004 - Access denied. User role has changed and the user no longer has permission to access this API.
AT005 - Access denied. You don't have permission to access this API. Please contact your administrator.
CE001 - Invalid or missing mandatory parameters.
CE002 - Something went wrong.
CE003 - Invalid username or password.

Copyright © 2023, ZOHO Corp. All Rights Reserved.