	Language	Title	Date
	en	DigDash REST API	2026/06/22 09:20
	es	-	-

Wiki source code of DigDash API REST

Last modified by Aurelie Bertrand on 2026/06/22 09:20

version	line-number	content
19.1	1	{{ddtoc/}}
	2
	3	----
	4
37.1	5	(% class="wikigeneratedid" %)
107.1	6	DigDash provides a REST API for interacting with a number of DigDash objects.
	7	You can use Swagger to test it.
37.1	8
107.1	9	= Accessing Swagger UI =
1.2	10
107.1	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.
1.2	13
107.1	14	To open Swagger UI, you can:
64.2	15
107.1	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:
53.1	21	[[http:~~/~~/localhost:8080/ddenterpriseapi/staticwebcontent/swagger/>>http://localhost:8080//ddenterpriseapi/staticwebcontent/swagger/]]
64.2	22	)))
1.2	23
107.1	24	This will take you to the interface displaying the available API resources, categorised by type.
1.2	25
32.1	26	(% class="box infomessage" %)
	27	(((
107.1	28	💡 If the domain name has been changed, you can specify a custom ddapi domain in the ‘domain’ field.
32.1	29	)))
	30
37.1	31	(% class="wikigeneratedid" %)
70.1	32	[[image:DigDash_API.png\|\|alt="Interface Swagger" height="770" width="1043"]]
37.1	33
107.1	34	= Authentication{{id name="Auth"/}} =
1.2	35
107.1	36	To interact with the APIs, you must authenticate.
1.2	37
107.1	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 indicates that 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(%%)(% 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" %)’ window will appear.
1.2	40
107.1	41	Three authorisation methods are available:
1.2	42
	43	* (((
107.1	44	BasicAuth: The Basic Authentication method, which allows you to log in using your LDAP username and password.
1.2	45	)))
	46	* (((
107.1	47	BearerAuth: The Bearer Authentication method, which uses security tokens known as bearer tokens.
1.2	48	)))
78.2	49	* (((
107.1	50	ApiKeyAuth: The API Key Authentication method, which allows you to authenticate using an API key.
78.2	51	)))
1.2	52
107.1	53	The BasicAuth method will be used for the first authentication. You can then generate a security token or an API key and use one of the other two methods.
1.2	54
	55	(% class="box warningmessage" %)
	56	(((
107.1	57	❗For security reasons, it is not recommended to use theBasicAuth method systematically.
1.2	58	)))
	59
25.1	60	(% class="box infomessage" %)
	61	(((
107.1	62	ℹ It is not possible to create a security token (JWT) when authenticated with a security token (JWT).
25.1	63	)))
	64
107.1	65	== Authenticating via BasicAuth ==
1.3	66
107.1	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.
1.3	71
107.1	72	== Authenticating via BearerAuth ==
1.3	73
107.1	74	Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.
80.1	75
107.1	76	=== Creating a JWT token{{id name="JWT"/}} ===
80.1	77
107.1	78	Here, we will create a JSON Web Token (JWT):
1.4	79
107.1	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 whose identity you wish to assume. This only works if the user used to create the JWT has the Admin > Allow identity borrowing* 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:
69.1	89	[[image:DigDash_API_token_creation_FR.png\|\|alt="Exemple authentification"]]
21.1	90
	91	(% class="box warningmessage" %)
	92	(((
107.1	93	❗A check will be carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
21.1	94	)))
	95
	96	(% start="5" %)
107.1	97	1. Click the Execute button to generate the token (JWT).
	98	➡ The response is displayed in the Server response section below.
69.1	99	[[image:DigDash_API_token_creation_response_FR.png\|\|alt="Réponse serveur"]]
107.1	100	1. Copy the JWT token.
3.1	101
81.1	102	(% class="wikigeneratedid" id="HSignaturedujetondesE9curitE9" %)
107.1	103	Signing the security token
9.1	104
107.1	105	A private key used to sign the JWT is generated by default. This key is temporary and is regenerated each time the server is restarted.
9.1	106
107.1	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:
9.1	108
107.1	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.
9.1	111
107.1	112	Please note that the DD_JWT_SECRETKEY_PATH variable takes precedence over the DD_JWT_SECRETKEY variable.
9.1	113
107.1	114	The RSA private key can be generated using the following command (requires the OpenSSL tool):
9.1	115
10.1	116	{{code language="shell"}}
71.1	117	openssl genrsa -out /path/to/privatekey.pem 2048
10.1	118	{{/code}}
9.1	119
107.1	120	The RSA public key can be generated from the private key using the following command (optional):
9.1	121
10.1	122	{{code language="shell"}}
	123	openssl rsa -in /path/to/privatekey.pem -pubout -out /path/to/publickey.crt
	124	{{/code}}
9.1	125
107.1	126	=== Authenticating ===
82.1	127
107.1	128	Once the security token has been generated, you can authenticate using this method:
82.1	129
107.1	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.
82.1	134
107.1	135	== Authenticating via ApiKeyAuth{{id name="ApiKeyAuth"/}} ==
78.2	136
107.1	137	Once logged in via BasicAuth, you can generate a security token to authenticate using the BearerAuth method.
92.1	138
107.1	139	=== Create an API key{{id name="API"/}} ===
80.1	140
107.1	141	We’re going to create an API key here:
78.2	142
107.1	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 impersonate* 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:
78.2	153	[[image:1745928168043-553.png]]
	154
	155	(% class="box warningmessage" %)
	156	(((
107.1	157	❗A check will be carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
78.2	158	)))
	159
	160	(% start="5" %)
107.1	161	1. Click the Execute button to generate the API key.
	162	➡ The response is displayed in the Server response section below.
78.2	163	[[image:1745928288556-250.png\|\|alt="Réponse serveur"]]
107.1	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.
99.1	167	)))
78.2	168
107.1	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//.
83.1	173
107.1	174	=== Authentication ===
7.1	175
107.1	176	Once the API key has been generated, you can authenticate using this method:
7.1	177
107.1	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.
5.4	182
107.1	183	= Available API resources{{id name="ressources"/}} =
15.2	184
107.1	185	== List of resources ==
18.1	186
107.1	187	The available resources are categorised by type:
15.2	188
107.1	189	* Authentication: for creating security tokens (JWT)
	190	* User Management: for managing users and related elements: profiles, roles, authorisation groups, role authorisation groups, 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.
15.2	196
20.1	197	(% class="box infomessage" %)
	198	(((
107.1	199	ℹ The closed padlock to the right of the resource indicates that you have authorisation.
20.1	200	)))
	201
107.1	202	== Available operations ==
15.3	203
107.1	204	There are several types of operations that can be performed via the API:
15.3	205
107.1	206	* (% style="color:#3498db" %)GET(%%): to retrieve information. For example, the list of users or system information.
	207	* (% style="color:#2ecc71" %)POST(%%): to create items. For example, a role or users within a licence.
	208	* (% style="color:#16a085" %)PATCH(%%): to update items (only replaces the data to be updated). For example, a user or a permissions group.
	209	* (% style="color:#e67e22" %)PUT(%%): to replace items (overwrites all data and replaces it).
	210	* (% style="color:#c0392b" %)DELETE(%%): to delete items. For example, a user’s permissions.
15.3	211
107.1	212	== Sending requests{{id name="envoi"/}} ==
20.1	213
60.1	214	(% class="box warningmessage" %)
	215	(((
107.1	216	❗Please note that a check is carried out on the user’s permissions in Digdash (ACLs) in addition to the token’s permissions.
60.1	217	)))
	218
26.1	219	(% style="line-height:1.7142857142857142; background-color:#ffffff; margin-bottom:15px; padding:3.75pt 0pt 0pt 0pt" %)
107.1	220	(% 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:
20.1	221
107.1	222	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.
	223	1. Before you begin, you can view an example request and, by hovering over the Schema tab, see a description of the various elements.
	224	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 on ‘Try it out ’.
	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" %)Specify the parameter values if necessary. A description is provided in the table below.
	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" %)Click ‘Execute’.(%%)
	227	➡(% 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.
	228	A bearer authorisation header is automatically used for your requests.
26.1	229
107.1	230	Swagger also provides curl command-line options when executing requests to help you test or code a tool outside the browser (in a script, for example).
	231	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.
58.1	232	[[image:1725441504464-493.png]]
	233
33.1	234	(% class="wikigeneratedid" id="HParamE8tres" %)
107.1	235	Settings
31.1	236
94.3	237	(% style="width:1391px" %)
	238	\|(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)User management
107.1	239	\|(% style="width:173px" %)includes\|(% style="width:1214px" %)You can add roles, authorisations (ACLs) and/or authorisation groups (groupACLs) to the query result.
	240	\|(% style="width:173px" %)id (required)\|(% style="width:1214px" %)Specify the name of the user, role, etc., depending on the API to be used for the operation.
	241	\|(% style="width:173px" %)resolveProfiles\|(% style="width:1214px" %)If set to //true//, and if the user has a profile, the profile information will be displayed.
	242	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.
94.3	243	\|(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)Session management
107.1	244	\|(% style="width:173px" %)users\|(% style="width:1214px" %)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.
94.3	245	\|(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)Connection management
107.1	246	\|(% style="width:173px" %)itemRole\|(% style="width:1214px" %)You can restrict the query to database connections limited to the roles specified here.
	247	\|(% style="width:173px" %)nameFilter\|(% style="width:1214px" %)You can restrict the query to database connections whose name contains the text string specified here.
	248	\|(% style="width:173px" %)typeFilter\|(% style="width:1214px" %)You can restrict the query to database connections of the type(s) specified here.
	249	\|(% style="width:173px" %)id (required)\|(% style="width:1214px" %)Specify the identifier for the database connection.
	250	\|(% colspan="2" style="background-color:grey; text-align:center; width:1388px" %)(% style="color:#ffffff" %)Licence management
	251	\|(% style="width:173px" %)pattern\|(% style="width:1214px" %)You can specify a regular expression to filter the users to be retrieved.
	252	For example, the pattern test.* will retrieve all users whose name begins with test.
31.1	253
107.1	254	= Authentication expiry =
35.1	255
	256	(% style="line-height:1.7142857142857142; background-color:#ffffff" %)
107.1	257	(% 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”.
	258	(% 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.
35.1	259
107.1	260	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.
	261	1. Click the Logout button below BearerAuth or ApiKeyAuth.
	262	1. Click Close to close the window.
	263	1. Generate a new access token or API key as described in the section [[Authenticating>>doc:\|\|anchor="Auth"]].
87.1	264
107.1	265	= Revoke a JWT token or API key =
87.1	266
107.1	267	== Revoking a JWT token ==
89.2	268
107.1	269	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.
87.2	270
107.1	271	== Revoking an API key ==
89.2	272
107.1	273	For an API key, revocation can be carried out on an individual or global basis.
87.2	274
107.1	275	To revoke one or more keys:
88.1	276
90.1	277	(% start="1" %)
107.1	278	1. You can first retrieve the list of API keys with their identifiers by using GET /api/v1/auth/apikeys. You will receive the list in the following format:
90.1	279	[[image:1745932166616-318.png\|\|alt="Liste clés API"]]
107.1	280	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
90.1	281
107.1	282	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.
90.1	283
	284
	285

Wiki source code of DigDash API REST

Sommaire