TOPdesk

Configuring TOPdesk integration

Tidal Control's TOPdesk integration connects to your TOPdesk ITSM instance to monitor operator access, incident handling, and change management for compliance purposes. All access is read-only — Tidal Control never creates, modifies, or deletes anything in TOPdesk.

What this integration monitors:

• Operators: Login permission, email, job title, branch, department, and ITSM role flags (first line, second line, change coordinator, installer, problem manager)
• Operator groups: Group membership per operator
• Permission groups: Which permission groups exist in your instance
• Incidents: Status, category, urgency, priority, response and completion dates, and major-call flag
• Change requests: Change type, status, phase, requester, category, impact, priority, and closing date

Requirements:

• Super User role in Tidal Control
• A TOPdesk operator account with API access and permission to create application passwords
• The Change Management module (optional) — only needed for the change management checks

Configuration step-by-step plan

What we're going to do: We'll set up the required permissions on a TOPdesk operator account, create an application password for that account, then add the connection in Tidal Control.

Configuration steps:

1. Set the required permissions on the operator account
2. Create an application password in TOPdesk
3. Configure the integration in Tidal Control

Step 1: Set the required permissions on the operator account

Use a dedicated operator account for the integration rather than a personal one. Permissions in TOPdesk are assigned per permission group, so set them on the permission group the account belongs to.

Permission	Access	Needed for
API access → REST API	Read	All API calls
API access → Use application passwords	Write	Authenticating with an application password
Supporting Files → Operators	Read	Operators and operator groups
Supporting Files → Permission Groups	Read	Permission groups

Step 2: Create an application password in TOPdesk

An application password is a separate token for API access. Use it instead of the operator's login password.

• Log in to your TOPdesk instance as the operator account from step 1
• Click your avatar in the top-right corner and choose My settings
• Scroll to Application passwords and click Add
• Enter a name (e.g. Tidal Control) and optionally an expiry date
• Click Save
• Copy the generated password — it is only shown once

Step 3: Configure the integration in Tidal Control

• Go to Settings → Integrations in Tidal Control
• Click the plus icon next to TOPdesk
• Fill in the configuration:
  • Name: A descriptive name, e.g. TOPdesk
  • API URL: Your TOPdesk instance URL, e.g. https://yourcompany.topdesk.net
  • Login name: The login name of the operator account from step 1
  • Application password: The password from step 2
• Click "Create" to save the integration

Configuration fields explained

Name:

• A descriptive name for this connection
• For example: TOPdesk, TOPdesk Production

API URL:

• The base URL of your TOPdesk instance, including https://
• For SaaS instances this is https://yourcompany.topdesk.net
• For self-hosted instances, use the URL you normally log in to
• Do not add a path such as /tas/api — Tidal Control appends that itself

Login name:

• The login name of the operator account, not its email address
• This must be the same account the application password was created for

Application password:

• The token generated in step 2, not the operator's login password
• Keep this value secure

Available checks

Access control (ISO 27001 A.9.2, A.9.4):

• Which operators have login access to the service desk
• Which ITSM roles each operator holds, for least-privilege and segregation-of-duties reviews
• Operator group and permission group membership as evidence for access reviews

Incident management (ISO 27001 A.16.1):

• Open and resolved security incidents with their category and priority
• Response and completion dates as SLA evidence
• Major incidents flagged for follow-up

Change management (ISO 27001 A.12.1.2):

• Change requests with their type, status, and phase as RFC lifecycle evidence
• Requester and handling operator for the change audit trail

Verification

Check integration status:

• Settings → Integrations shows "Connected" status for TOPdesk
• TOPdesk tests are available in the Tests section
• Test refresh delivers results without authentication errors

Frequently asked questions

Does Tidal Control make changes in TOPdesk? No. The integration is read-only and only reads operator, incident, and change data.

Can I use the operator's normal login password? No. Use an application password. TOPdesk's REST API requires one, and it can be revoked without changing the operator's password.

Does this work with a self-hosted TOPdesk instance? Yes. Enter the URL you normally log in to as the API URL. The account and permission requirements are the same.

Do I need the Change Management module? Only for the change management checks. Everything else works without it.

Common problems

Authentication fails with a 401 error

• Check that the Login name is the operator's login name, not its email address
• Confirm the application password was copied in full and belongs to that same operator account
• The password may have expired or been revoked — create a new one and update the integration

Tests fail with a 403 error

• The operator's permission group is missing one of the permissions from step 1
• Check API access → REST API (Read) and API access → Use application passwords (Write) in particular

Change management checks return no results

• The Change Management module is probably not licensed or enabled on your instance
• Confirm you can open the Changes module in TOPdesk yourself with the same account

No operators or permission groups are returned

• Add Supporting Files → Operators (Read) and Supporting Files → Permission Groups (Read) to the operator's permission group

Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.