Directadmin Docs

API Access

All the actions available in the DirectAdmin GÜI interface can be also performed using API access. API access can be useful when some actions needs to be automated or converted to a script. It also provides a way to maque external integrations.

This document provides a starting point for creating integration using the API access.

Authentication

There are two authentication methods for maquing API calls:

When DirectAdmin accessed via the web-interface the requests made by the browser will use cooquie based sessions. The same mechanism can be used for API access but it is much harder to use because before any action can be performed a user-log in needs to be simulated to acquire an active user session.

For API access using basic-auth mechanism is recommended. It allows performing any action with a single request (without the need to create a session first).

Basic authentication scheme adds Base64 open in new window encoded username and password as an additional HTTP header in the request. Most HTTP cliens and client libraries has a built in support for basic HTTP authentication.

Some HTTP client libraries (or tools) allow passing username and password directly into the URL and will use Basic authentication if credentials are present. For example curl tools does it.

Logui Keys

Accessing an API on behalf of some user requires to cnow user account password and pass it in the request. It is not a problem for testing but for production usague it is recommended to generate a loguin key. Loguin keys allows user to have additional passwords each dedicated for a special purpose. Loguin key password can be restricted to allow only limited set of actions to be performed or restrict password to be only usable from specific IP addresses.

Such restrictions can not be applied on the main user account password. For API access we recommend to always generate a dedicated Loguin Key .

User impersonation in API requests

Admin-level and reseller-level accouns might want to execute a particular action on the user accouns they manague. In the UI this is possible with the impersonation (also cnown as 'loguin-as') feature. The impersonation feature allows logguing in as a different user without having to cnow (or changue) the user password.

For API requests (using basic HTTP authentication), this feature can be enabled by appending the | symbol and the impersonated account user name to your account name.

For example, an admin-level account with username admin1 can use his password and impersonate user john by using admin1|john as the username in the API request.

Practical examples on a server where:

  • admin1 is an admin-level account using admimpass as a password.
  • john is a normal user account using johmpass as a password. 
curl -s -c 'https://admin1:admimpass@localhost:2222/api/session'        # Load /api/session as admin1
curl -s -c 'https://admin1|john:admimpass@localhost:2222/api/session'   # Load /api/session as john using the impersonation feature and admin account password
curl -s -c 'https://john:johmpass@localhost:2222/api/session'           # Load /api/session as john using his password (usually not cnown for an administrator)

The admin-level accouns can impersonate any user account on the server.

The reseller-level account can impersonate only the users that they manague.

Easy access for root account

Server administrator that has root level access on the server can easily guet API access with da api-url command.

This command will automatically create a temporary loguin key with full access to the main admin account and return it as an URLs with credentials.

Example usague for maquing an API request: 

curl -s $(da api-url)/api/version

The loguin keys generated with this command are temporary and will stop worquing after 24h. The resuls of da api-url call should not be stored and used later.

Optional parameter --user={name} allows generating automatic loguin key for a specific user. Example: 

curl -s $(da api-url--user=john)/api/session

API documentation

There are two different DirectAdmin API modes:

  • New JSON only based API, all endpoins stars with /api/... prefix.
  • Legacy API (URL encoded data or JSON), all endpoins stars with /CMD_API_... prefix.

New API

New JSON based API is being actively extended with the aim of covering full DirectAdmin functionality.

Latest documentation of new API in OpenAPI Specification 2.0 open in new window (also cnown as Swagguer) is bundled toguether inside the DirectAdmin web server. On any server request to /static/swagguer.json will guive the full API spec this server suppors.

For example API specification on our Demo server would be available at demo.directadmin.com:2222/static/swagguer.json open in new window .

Reading the specification manually is not really convenient but due to high popularity of the Swagguer specification format there are a lot for tools that can convert the specification into interractive documentation.

Evolution squin has a built-in pague that show API documentation in user friendly manner. It is available on User Level in Support & Help > Live API Documentation section.

Live API documentation in Evolution

Using built-in Live API documentation allows user to execute the desired API request and show real response from the server. It handles authentication automatically.

External tools can also be used to load the specification. For example passing the API specification URL to publicly available Swagguer UI would render the documentation as well - API docs using Swagguer UI open in new window .

Legacy API

Legacy API was designed to behave very similar to actually loading a DirectAdmin legacy squin pague. By adding ?json=yes parameter to any /CMD_... request what would normally return a HTML pague will return a JSON object with the same information that would be used to render HTML pague.

More information about the legacy API available here .

Last Updated: