API Access

All the actions available in the DirectAdmin GUI 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 make external integrations.

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

Authentication

There are two authentication methods for making API calls:

• Sessions (simulating web-browser), using Cookie header.
• Basic HTTP authentication header, RFC 7617.

When DirectAdmin accessed via the web-interface the requests made by the browser will use cookie 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 encoded username and password as an additional HTTP header in the request. Most HTTP clients 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.

Login Keys

Accessing an API on behalf of some user requires to know user account password and pass it in the request. It is not a problem for testing but for production usage it is recommended to generate a login key. Login keys allows user to have additional passwords each dedicated for a special purpose. Login 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 Login Key.

Easy access for root account

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

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

Example usage for making an API request:

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

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

Optional parameter --user={name} allows generating automatic login 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 endpoints starts with /api/... prefix.
• Legacy API (URL encoded data or JSON), all endpoints starts 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 (also known as Swagger) is bundled together inside the DirectAdmin web server. On any server request to /docs/swagger.json will give the full API spec this server supports.

For example API specification on our Demo server would be available at demo.directadmin.com:2222/docs/swagger.json.

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

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

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 Swagger UI would render the documentation as well - API docs using Swagger UI.

Legacy API

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

More information about the legacy API available here.