• Accessing Swagger UI
• Authentication
  • Authenticating via BasicAuth
  • Authenticating via BearerAuth
    • Creating a JWT token
    • Authenticating
  • Authenticating via ApiKeyAuth
    • Create an API key
    • Authentication
• Available API resources
  • List of resources
  • Available operations
  • Sending requests
• Authentication expiry
• Revoke a JWT token or API key
  • Revoking a JWT token
  • Revoking an API key

DigDash provides a REST API for interacting with a number of DigDash objects.
You can use Swagger to test it.

Accessing Swagger UI

Swagger UI allows you to view and interact with API resources.
This interface also provides visual documentation to make them easier to use.

To open Swagger UI, you can:

• click on the API link at the bottom of the homepage
• use the following link:

  http://[server]:[port]/[domain]/staticwebcontent/swagger/
  where you replace [server], [port] and [domain] with your own details.
  For example:
  http://localhost:8080/ddenterpriseapi/staticwebcontent/swagger/

This will take you to the interface displaying the available API resources, categorised by type.

Authentication

To interact with the APIs, you must authenticate yourself.

• Click the ‘Authorise’button in the top right-hand corner of the Digdash API page. (The open padlock icon means you are not authorised.)
  ➡The ‘Availableauthorisations’window will appear.

Three authorisation methods are available:

• BasicAuth: The Basic Authentication method, which allows you to log in using your LDAP username and password.

• BearerAuth: The Bearer Authentication method, which uses security tokens known as bearer tokens.

• ApiKeyAuth: The API Key Authentication method, which allows you to authenticate using an API key.

The BasicAuth method will be used for the initial authentication. You can then generate a security token or an API key and use one of the other two methods.

Authenticating via BasicAuth

1. Enter your Digdash username and password.
2. Click the ‘Authorise’ button, then, once authentication is complete, click ‘Close’.
   ➡ The padlock is now closed, indicating that you are authorised.
   You can now create a JWT token or an API key to log in.

Authenticating via BearerAuth

Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.

Creating a JWT token

Here, we will create a JSON Web Token (JWT):

1. Go to the Authentication section.
2. Click to expandPOST ddenterpriseapi/api/v1/auth/jwt.
3. Before you begin, you can view an example request and, by hovering over the Schema tab, a description of the various elements.
4. Click on ‘Try it out’ in the top right-hand corner to define your request. This includes the following elements:
   • targetUser: (Optional) Specify the name of the user to impersonate. This only works if the user used to create the JWT has the Admin > Allow impersonation authorisation (ACL).
     If left blank, the default user is the one currently logged in, which will generally be the case.
   • expires: (Optional but recommended) Specify the JWT’s validity period in the form of a time period in ISO 8601 format (e.g. PT5M for 5 minutes). For further information, see https://en.wikipedia.org/wiki/ISO_8601#Durations.⚠ Only the PnDTnHnMnS format is supported: you can specify days, hours, minutes and seconds, but not years, months or weeks (PnYnMnWnDTnHnMnS).
   • Permissions: Set the permissions for each API type: “none” for no permissions, “r” for read-only, “rw” for read-write.
     For example:
     

5. Click theExecute buttonto generate the token (JWT).
   ➡ The response is displayed in the Server response section below.
   
6. Copy the JWT token.
   

Signing the security token

A private key used to sign the JWT is generated by default. This key is temporary and is regenerated every time the server is restarted.

To avoid this issue and improve security, it is strongly recommended that you use your own private key to sign JWT tokens using the following environment variables:

• DD_JWT_SECRETKEY_PATH: this variable is used to specify the path to an RSA private key.
• DD_JWT_SECRETKEY: this variable allows you to define a custom password.

Please note that the DD_JWT_SECRETKEY_PATH variable takes precedence over the DD_JWT_SECRETKEY variable.

The RSA private key can be generated using the following command (requires the OpenSSL tool):

The RSA public key can be generated from the private key using the following command (optional):

Authenticating

Once the security token has been generated, you can authenticate using this method:

1. Click theAuthorise button.
2. In theBasicAuth section, log out by clicking theLogout button.
3. In theBearerAuth section, paste the JWT token into theValue field.
4. ClickAuthorise.

Authenticating via ApiKeyAuth

Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.

Create an API key

We’re going to create an API key here:

1. Go to the Authentication section.
2. Click to expandPOST ddenterpriseapi/api/v1/auth/apikeys
3. Before you begin, you can view an example request and, by hovering over the Schema tab, a description of the various elements.
4. Click on ‘Try it out’ in the top right-hand corner to define your request. This includes the following elements:
   • targetUser: (Optional) Specify the name of the user whose identity you wish to assume. This only works if the user used to create the API key has the Admin > Allow identity borrowing authorisation (ACL).
     If left blank, the default user is the one currently logged in, which will generally be the case.
   • expires: (Optional) Specify the validity period of the API key in the form of a time period in ISO 8601 format (i.e. PT5M for 5 minutes). For further information, see https://en.wikipedia.org/wiki/ISO_8601#Durations.⚠ Only the PnDTnHnMnS format is supported: you can specify days, hours, minutes and seconds, but not years, months or weeks (PnYnMnWnDTnHnMnS).
     If the ‘expires’ element is not included in the request, the key has an infinite duration.
   • permissions: Set the permissions for each API type: “none” for no permissions, “r” for read-only, “rw” for read-write.
     For example:
     

5. Click theExecute buttonto generate the API key.
   ➡ The response is displayed in the Server response section below.
   
6. Copy the API key.
   ❗The key is only displayed once and cannot be retrieved in any other way, as it is hashed (irreversibly encrypted) when stored on the server for security reasons.

   If a key is lost or no longer required, it must be invalidated and a new key created if necessary.

The API key is stored on the server in a CSV file named apikeys.csv, located by default in the appdata/EnterpriseServer/ddenterpriseapi/config directory.
However, if a custom location has been defined via the ddenterpriseapi.ServerSettingsPathin the digdash.properties file, this configuration takes precedence over the default path.
You can change this directory, or specify multiple directories in the case of multiple domains, in the digdash.propertiesfile by adding them in the following format: ddenterprise.api_keys_path=/path/to/csv-file. 
This property takes precedence over ddenterpriseapi.ServerSettingsPath.

Authentication

Once the API key has been generated, you can authenticate using this method:

1. Click the Authorise button.
2. In the BasicAuth section, log out by clicking the Logout button.
3. In the ApiKeyAuth section, paste the API key into the Value field.
4. Click Authorise.

Available API resources

List of resources

The available resources are categorised by type:

• Authentication: for creating security tokens (JWT)
• User Management: for managing users and related elements: profiles, roles, authorisation groups, role authorisation groups, user settings, etc.
• Session Management: for retrieving the list of sessions and terminating sessions.
• System: for system information, audit service and scheduler.
• Licence Management: for managing licences: activation, users covered by the licence, etc.
• Event Management: for adding events using fireEvent.
• Connections: for managing database connections: listing, creating, replacing and deleting.
• Versions: for retrieving the version of the API or Digdash.

Available operations

There are several types of operations that can be performed via the API:

• GET: to retrieve information. For example, the list of users or system information.
• POST: to create items. For example, a role or users within a licence.
• PATCH: to update items (only replaces the data to be updated). For example, a user or a permissions group.
• PUT: to replace items (overwrites all data and replaces it).
• DELETE: to delete items. For example, a user’s permissions.

Sending requests

Once you have been authorised, you can make requests:

1. Expand the resource on which you wish to perform an operation. A closed padlock indicates that you are authorised.
2. Before you begin, you can view an example request and, by hovering over theSchema tab, see a description of the various elements.
3. In the expanded method window, click ‘Try it out ’.
4. Specify the parameter values if necessary. A description is provided in the table below.
5. Click ‘Execute’.
   ➡The request is executed and the response is displayed.
   A bearer authorisation header is automatically used for your requests.

Swagger also provides curl command-line options when executing requests to help with testing or coding a tool outside the browser (in a script, for example).
Please note that, whether using curl or another tool, you must specify the HTTP headers “Accept” (format of the content to be retrieved) and “Content-Type” (format of the content sent) for the requests to work correctly. These two headers can take the values “application/json” for JSON or “application/xml” for XML.

Settings

Authentication expiry

When the security token (JWT) or API key expires, you will receive a 401response :“Unauthorised”.
The Bearer authorisation header is still present in your requests, but the token has expired. When this happens, you must log out of BearerAuth and generate a new access token.

1. Click the Authorise button to open the Available authorisations window.
2. Click the Logout button belowBearerAuth or ApiKeyAuth.
3. ClickClose to close the window.
4. Generate a new access token or API key as described in the section Authenticating.

Revoke a JWT token or API key

Revoking a JWT token

For a JWT token, revocation is carried out globally only by changing the private key used for signing and the associated public key used to validate signatures.

Revoking an API key

For an API key, revocation can be carried out on an individual or global basis.

To revoke one or more keys:

1. You can first retrieve the list of API keys and their identifiers by usingGET /api/v1/auth/apikeys. You will receive the list in the following format:
   
   
2. Send a list of identifiers (in JSON or XML depending on the Content-Type, as explained in the section Sending Requests) to "POST /api/v1/auth/apikeys/delete" to revoke one or more keys

To revoke all API keys, either delete all keys as described above or delete the csv file `apikeys.csv` containing the keys whilst the server is switched off.