Wiki source code of DigDash API REST

Last modified by Aurelie Bertrand on 2026/06/19 10:37
Show last authors
1 {{ddtoc/}}
2
3 ----
4
5 (% class="wikigeneratedid" %)
6 DigDash provides a REST API for interacting with a number of DigDash objects.
7 You can use Swagger to test it.
8
9 = Accessing Swagger UI =
10
11 Swagger UI allows you to view and interact with API resources.
12 This interface also provides visual documentation to make them easier to use.
13
14 To open Swagger UI, you can:
15
16 * click on the **API** link at the bottom of the homepage
17 * use the following link:(((
18 [[http:~~/~~/~[server~]:~[port~]/~[domain~]/staticwebcontent/swagger/>>url:http://[serveur]:[port]/[domain]/updateuser]]
19 where you replace [server], [port] and [domain] with your own details.
20 For example:
21 [[http:~~/~~/localhost:8080/ddenterpriseapi/staticwebcontent/swagger/>>http://localhost:8080//ddenterpriseapi/staticwebcontent/swagger/]]
22 )))
23
24 This will take you to the interface displaying the available API resources, categorised by type.
25
26 (% class="box infomessage" %)
27 (((
28 💡 If the domain name has been changed, you can specify a custom ddapi domain in the **‘domain’** field.
29 )))
30
31 (% class="wikigeneratedid" %)
32 [[image:swagger.png||alt="Interface Swagger" height="770" width="1043"]]
33
34 = Authentication{{id name="Auth"/}} =
35
36 To interact with the APIs, you must authenticate yourself.
37
38 * (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Click the (%%)**‘Authorise’**(% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)button in the top right-hand corner of the Digdash API page. (The open padlock icon means you are not authorised.)(%%)
39 ➡(% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)The (%%)**‘Available**(% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)authorisations’window will appear.
40
41 Three authorisation methods are available:
42
43 * (((
44 **BasicAuth: **The Basic Authentication method, which allows you to log in using your LDAP username and password.
45 )))
46 * (((
47 **BearerAuth**: The Bearer Authentication method, which uses security tokens known as bearer tokens.
48 )))
49 * (((
50 **ApiKeyAuth**: The API Key Authentication method, which allows you to authenticate using an API key.
51 )))
52
53 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.
54
55 (% class="box warningmessage" %)
56 (((
57 ❗For security reasons, it is not recommended to use the**BasicAuth** method systematically.
58 )))
59
60 (% class="box infomessage" %)
61 (((
62 ℹ It is not possible to create a security token (JWT) when authenticated with a security token (JWT).
63 )))
64
65 == Authenticating via BasicAuth ==
66
67 1. Enter your Digdash username and password.
68 1. Click the **‘Authorise’** button, then, once authentication is complete, click **‘Close**’.
69 ➡ The padlock is now closed, indicating that you are authorised.
70 You can now create a JWT token or an API key to log in.
71
72 == Authenticating via BearerAuth ==
73
74 Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.
75
76 === Creating a JWT token{{id name="JWT"/}} ===
77
78 Here, we will create a JSON Web Token (JWT):
79
80 1. Go to the **Authentication** section.
81 1. Click to expand**POST ddenterpriseapi/api/v1/auth/jwt.**
82 1. Before you begin, you can view an example request and, by hovering over the **Schema** tab, a description of the various elements.
83 1. Click on **‘Try it out’ in **the top right-hand corner to define your request. This includes the following elements:
84 1*. **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).
85 If left blank, the default user is the one currently logged in, which will generally be the case.
86 1*. **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>>https://en.wikipedia.org/wiki/ISO_8601#Durations]].(% style="color:#d35400" %)⚠ Only the PnDTnHnMnS format is supported: (%%)you can specify days, hours, minutes and seconds, but not years, months or weeks (PnYnMnWnDTnHnMnS).
87 1*. **Permissions: **Set the permissions for each API type: “none” for no permissions, “r” for read-only, “rw” for read-write.
88 For example:
89 [[image:DigDash_API_token_creation_FR.png||alt="Exemple authentification"]]
90
91 (% class="box warningmessage" %)
92 (((
93 ❗A check will be carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
94 )))
95
96 (% start="5" %)
97 1. Click the**Execute **button**to **generate the token (JWT).
98 ➡ The response is displayed in the **Server response** section below.
99 [[image:DigDash_API_token_creation_response_FR.png||alt="Réponse serveur"]]
100 1. Copy the JWT token.\\
101
102 (% class="wikigeneratedid" id="HSignaturedujetondesE9curitE9" %)
103 **Signing the security token**
104
105 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.
106
107 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:
108
109 * **DD_JWT_SECRETKEY_PATH**: this variable is used to specify the path to an RSA private key.
110 * **DD_JWT_SECRETKEY**: this variable allows you to define a custom password.
111
112 Please note that the DD_JWT_SECRETKEY_PATH variable takes precedence over the DD_JWT_SECRETKEY variable.
113
114 The RSA private key can be generated using the following command (requires the OpenSSL tool):
115
116 {{code language="shell"}}
117 openssl genrsa -out /path/to/privatekey.pem 2048
118 {{/code}}
119
120 The RSA public key can be generated from the private key using the following command (optional):
121
122 {{code language="shell"}}
123 openssl rsa -in /path/to/privatekey.pem -pubout -out /path/to/publickey.crt
124 {{/code}}
125
126 === Authenticating ===
127
128 Once the security token has been generated, you can authenticate using this method:
129
130 1. Click the**Authorise** button.
131 1. In the**BasicAuth** section, log out by clicking the**Logout** button.
132 1. In the**BearerAuth** section, paste the JWT token into the**Value** field.
133 1. Click**Authorise**.
134
135 == Authenticating via ApiKeyAuth{{id name="ApiKeyAuth"/}} ==
136
137 Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.
138
139 === Create an API key{{id name="API"/}} ===
140
141 We’re going to create an API key here:
142
143 1. Go to the **Authentication** section.
144 1. Click to expand**POST ddenterpriseapi/api/v1/auth/apikeys**
145 1. Before you begin, you can view an example request and, by hovering over the **Schema** tab, a description of the various elements.
146 1. Click on **‘Try it out’ in **the top right-hand corner to define your request. This includes the following elements:
147 1*. **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).
148 If left blank, the default user is the one currently logged in, which will generally be the case.
149 1*. **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>>https://en.wikipedia.org/wiki/ISO_8601#Durations]].(% style="color:#d35400" %)⚠ Only the PnDTnHnMnS format is supported(%%): you can specify days, hours, minutes and seconds, but not years, months or weeks (PnYnMnWnDTnHnMnS).
150 If the //‘expires’// element is not included in the request, the key has an infinite duration.
151 1*. **permissions: **Set the permissions for each API type: “none” for no permissions, “r” for read-only, “rw” for read-write.
152 For example:
153 [[image:1745928168043-553.png]]
154
155 (% class="box warningmessage" %)
156 (((
157 ❗A check will be carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
158 )))
159
160 (% start="5" %)
161 1. Click the**Execute **button**to **generate the API key.
162 ➡ The response is displayed in the **Server response** section below.
163 [[image:1745928288556-250.png||alt="Réponse serveur"]]
164 1. Copy the API key.
165 ❗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.(((
166 If a key is lost or no longer required, it must be invalidated and a new key created if necessary.
167 )))
168
169 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.
170 However, if a custom location has been defined via the **//ddenterpriseapi.ServerSettingsPath//**in the //digdash.properties// file, this configuration takes precedence over the default path.
171 You can change this directory, or specify multiple directories in the case of multiple domains, in the //digdash.properties//file by adding them in the following format//: ddenterprise.api_keys_path=/path/to/csv-file. //
172 This property takes precedence over //ddenterpriseapi.ServerSettingsPath//.
173
174 === Authentication ===
175
176 Once the API key has been generated, you can authenticate using this method:
177
178 1. Click the **Authorise** button.
179 1. In the **BasicAuth** section, log out by clicking the **Logout** button.
180 1. In the **ApiKeyAuth** section, paste the API key into the Value field.
181 1. Click **Authorise**.
182
183 = Available API resources{{id name="ressources"/}} =
184
185 == List of resources ==
186
187 The available resources are categorised by type:
188
189 * **Authentication: **for creating security tokens (JWT)
190 * **User Management**: for managing users and related elements: profiles, roles, authorisation groups, role authorisation groups, user settings, etc.
191 * **Session Management: **for retrieving the list of sessions and terminating sessions.
192 * **System**: for system information, audit service and scheduler.
193 * **Licence Management**: for managing licences: activation, users covered by the licence, etc.
194 * **Event Management**: for adding events using fireEvent.
195 * **Connections: **for managing database connections: listing, creating, replacing and deleting.
196 * **Versions**: for retrieving the version of the API or Digdash.
197
198 (% class="box infomessage" %)
199 (((
200 ℹ The closed padlock to the right of the resource indicates that you have authorisation.
201 )))
202
203 == Available operations ==
204
205 There are several types of operations that can be performed via the API:
206
207 * (% style="color:#3498db" %)**GET**(%%): to retrieve information. For example, the list of users or system information.
208 * (% style="color:#2ecc71" %)**POST**(%%): to create items. For example, a role or users within a licence.
209 * (% style="color:#16a085" %)**PATCH**(%%)**: **to update items (only replaces the data to be updated). For example, a user or a permissions group.
210 * (% style="color:#e67e22" %)**PUT**(%%)**: **to replace items (overwrites all data and replaces it).
211 * (% style="color:#c0392b" %)**DELETE**(%%): to delete items. For example, a user’s permissions.
212
213 == Sending requests{{id name="envoi"/}} ==
214
215 (% class="box warningmessage" %)
216 (((
217 ❗Please note that a check is carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
218 )))
219
220 (% style="line-height:1.7142857142857142; background-color:#ffffff; margin-bottom:15px; padding:3.75pt 0pt 0pt 0pt" %)
221 (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Once you have been authorised, you can make requests:
222
223 1. (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Expand the resource on which you wish to perform an operation. A closed padlock indicates that you are authorised.
224 1. Before you begin, you can view an example request and, by hovering over the**Schema** tab, see a description of the various elements.
225 1. (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)In the expanded method window, click **‘Try it out **’.
226 1. (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Specify the parameter values if necessary. A description is provided in the table below.
227 1. (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Click **‘Execute’.**(%%)
228 ➡(% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)The request is executed and the response is displayed.
229 A bearer authorisation header is automatically used for your requests.
230
231 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).
232 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.
233 [[image:1725441504464-493.png]]
234
235 (% class="wikigeneratedid" id="HParamE8tres" %)
236 **Settings**
237
238 (% style="width:1391px" %)
239 |(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)**User management**
240 |(% style="width:205px" %)includes|(% style="width:1184px" %)You can add roles, authorisations (ACLs) and/or authorisation groups (groupACLs), as well as licence information, to the query result.
241 |(% style="width:205px" %)id (required)|(% style="width:1184px" %)Specify the name of the user, role, etc., depending on the API to be used for the operation.
242 |(% style="width:205px" %)resolveGroupAcls|(% style="width:1184px" %)If set to //true//, the permissions that are part of the profile’s authorisation groups are displayed.
243 |(% style="width:205px" %)resolveProfiles|(% style="width:1184px" %)If set to //true//, and if the user has a profile, the profile information will be displayed.
244 For example, if the user has roles derived from a profile, the roles from the profile will be displayed rather than the user’s own roles.
245 |(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)**Session management**
246 |(% style="width:205px" %)users|(% style="width:1184px" %)You can specify users for the query: click the **‘Add string item’** button and enter a user’s name. Repeat this step as required for other users.        
247 |(% style="width:205px" %)id|(% style="width:1184px" %)Specify the session name.
248 |(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)**System**
249 |(% style="width:205px" %)period number|(% style="width:1184px" %)Specify the period for which to retrieve the latest cube and security failures in DDAudit (60 seconds by default).
250 |(% style="width:205px" %)auditService|(% style="width:1184px" %)Specify the audit service of your choice: ChangeAuditor, FlowAuditor, SystemAuditor, CubeAuditor, SecurityAuditor, DashboardAuditor or SessionAuditor.
251 |(% style="width:205px" %)syncher|(% style="width:1184px" %)(((
252 Specify the synchroniser of your choice: PlayTP, SyncTP, CopyTP or ExportTP.
253 )))
254 |(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)**Connection management**
255 |(% style="width:205px" %)itemRole|(% style="width:1184px" %)You can restrict the query to database connections limited to the roles specified here.
256 |(% style="width:205px" %)nameFilter|(% style="width:1184px" %)You can restrict the query to database connections whose name contains the text string specified here.
257 |(% style="width:205px" %)typeFilter|(% style="width:1184px" %)You can restrict the query to database connections of the type(s) specified here.
258 |(% style="width:205px" %)id (required)|(% style="width:1184px" %)Specify the identifier for the database connection.
259 |(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)**Licence management**
260 |(% style="width:205px" %)pattern|(% style="width:1184px" %)You can specify a regular expression to filter the users to be retrieved.
261 For example, the pattern test.* will retrieve all users whose name begins with test.
262
263 = Authentication expiry =
264
265 (% style="line-height:1.7142857142857142; background-color:#ffffff" %)
266 (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)When the security token (JWT) or API key expires, you will receive a (% style="color:#182027; font-family:~"Roboto Mono~",monospace; font-size:10pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)401(% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)response (% style="color:#182027; font-family:~"Roboto Mono~",monospace; font-size:10pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %):(%%)“Unauthorised”.
267 (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)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.
268
269 1. (% style="color:#182027; font-family:Arial,sans-serif; font-size:10.5pt; font-style:normal; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)Click the **Authorise** button to open the **Available authorisations** window.
270 1. Click the **Logout** button below**BearerAuth or ApiKeyAuth**.
271 1. Click**Close** to **close** the window.
272 1. Generate a new access token or API key as described in the section [[Authenticating>>doc:||anchor="Auth"]].
273
274 = Revoke a JWT token or API key =
275
276 == Revoking a JWT token ==
277
278 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.
279
280 == Revoking an API key ==
281
282 For an API key, revocation can be carried out on an individual or global basis.
283
284 To revoke one or more keys:
285
286 (% start="1" %)
287 1. You can first retrieve the list of API keys and their identifiers by using**GET /api/v1/auth/apikeys**. You will receive the list in the following format:
288 [[image:1745932166616-318.png||alt="Liste clés API"]]\\
289 1. Send a list of identifiers (in JSON or XML depending on the Content-Type, as explained in the section [[Sending Requests>>doc:||anchor="envoi"]]) to "POST /api/v1/auth/apikeys/delete" to revoke one or more keys
290
291 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.