API tokens

API Tokens

The API Tokens screen is where you create, review, and revoke the bearer credentials that allow external systems to communicate with DPMS programmatically. If you are connecting an identity provider for automated user provisioning, enabling the AI assistant, or integrating a custom tool with the DPMS API, you will need to generate a token here first. Without a valid, active token of the correct type, none of those integrations can authenticate — making this screen a foundational step for everything that touches DPMS from outside a browser.

How to open it

Navigate to IT Settings in the left sidebar, expand Identity & Access Management (IAM), and click API Tokens. The full path in the breadcrumb reads: IT Settings › Identity & Access Management › API Tokens.

You need the IAM read permission to view the screen. The Create token button is only visible to users who also have the IAM edit permission. If you lack the read permission entirely, DPMS shows a standard access-denied page rather than hiding the menu item.

What you see

The screen is divided into a standard DPMS layout: the left sidebar shows the IAM sub-navigation with API Tokens highlighted, and a breadcrumb trail at the top lets you jump to adjacent IAM sections using the small arrow icons on either side of the page title.

Below the breadcrumb, a bold blue heading reading API Tokens is followed by a full-width dividing line. The main area is a scrollable data table with two filter tabs — Active and Expired — sitting just above the rows. A Create token button sits in the upper-right corner of the table section (visible only if you have edit permission). As you scroll toward the bottom of a long list, additional tokens load automatically without any page reload.

Each row in the table represents one token and shows its name, creation date, expiration date, type, a masked version of the token string, and the date it was last used by an integration.

Working with this screen

Generating a new token for the first time

The most common reason to visit this screen is to connect a new external system. Start by clicking Create token in the upper-right corner. A small dropdown appears confirming the action — click the item inside it to proceed to the creation form.

On the creation form, fill in the Name field first. Choose something descriptive that will still make sense six months from now, for example "Workday SCIM Connector – HR Onboarding" or "AI Agent – EU Cluster." A clear name is your only audit trail for why each credential exists, so be specific.

Next, open the Type dropdown and select the integration context:

• Choose SCIM if you are connecting an identity provider such as Microsoft Entra ID or Okta to synchronise users automatically.
• Choose MCP if you are enabling AI-assisted features — the AI assistant, automatic risk scoring, or any tool that talks to the DPMS AI layer.

Once you have selected MCP as the type, a read-only URL field appears at the bottom of the form. This is the exact endpoint your AI client must connect to (for example, https://dpms.yourcompany.com/pp/mcp/v1/abc123/mcp). There is a copy icon to the right of the URL; click it and the icon briefly changes to a check mark to confirm the address is in your clipboard. Copy this URL now — you will need it alongside the token itself.

Now set the Validity. The dropdown offers preset options of 182, 365, 548, or 731 days. Selecting any of these immediately fills in the Expiration date field below so you can see exactly when the token will stop working. If none of the presets fit your needs, choose Custom and type the number of days directly into the field that appears. Note that the maximum allowed custom period is 3,652 days (ten years); if you enter a higher number it will be silently reduced to 3,652, so always check the calculated expiration date before saving.

The optional Comment field is worth filling in even though it is not required. Record who requested the token, the ticket or change-request number, and the purpose. This information appears on the token's detail page and helps auditors understand your credential inventory without needing to contact you.

When everything looks correct, click Save. Before the token is actually created, a confirmation toast slides in at the bottom of the screen with a warning message. You must click the confirm button inside that toast to proceed. If you miss the toast or it disappears before you act, simply click Save again — the token has not been created yet.

After you confirm, DPMS calls the token generation service. On success, the browser takes you straight to the token reveal screen.

Copying the token on the reveal screen

The reveal screen appears only once, immediately after a new token is created. It is not shown when you later view or edit the token.

You will see the full bearer token string in a password-type input field. Click the copy icon next to it — the icon switches to a check mark for a moment to confirm the copy. Paste the token somewhere safe immediately — a password manager, a secrets vault, or your integration tool's configuration. Once you navigate away from this screen, DPMS will never show you the full token again. Only a masked version (like eyJhbGci…••••••) will appear in the token list. If you lose the token, the only option is to delete it and create a new one.

After copying, navigate back to the token list. The new token now appears in the Active tab with its creation date, expiration date, and type visible.

Reviewing active tokens and checking last usage

Click the Active tab (the default view) to see every token that is currently valid. Scan the Last date used column to spot credentials that have never been used or that have not been used recently — these may belong to integrations that were never fully set up, or systems that are no longer in production.

To see more detail about a specific token, click anywhere on its row. This opens the token's edit/detail form. Here you can update the Name or Comment, confirm the expiration date, and see the masked token string. The Type selector is greyed out on this form — the type is set permanently at creation time and cannot be changed.

If you need to update a token's name or comment (for example, because the responsible team or system name has changed), make your edits and click Save. The change is applied immediately with no confirmation toast.

Cleaning up expired tokens

Switch to the Expired tab to see tokens that have passed their validity date. Expired tokens can no longer be used by integrations, but they remain visible here for audit purposes — they are not cleaned up automatically.

To remove a specific expired token, hover over its row until the three-dot menu icon appears at the right edge of the row. Click the icon and select Delete. A confirmation step fires before the record is permanently removed. Repeat the process for any other stale tokens.

Keeping the Expired tab tidy matters because during an audit you may be asked to confirm that every credential in the system was intentional. A long list of old, undeleted tokens can raise unnecessary questions.

Revoking an active token immediately

If an integration is being decommissioned, a team member with access to a token has left the organisation, or you suspect a credential has been compromised, you should delete the token straight away. Hover over its row in the Active tab, click the three-dot menu, and select Delete. After you confirm, the token is removed permanently from the backend. Any system that was using it will immediately start receiving authentication errors — there is no grace period. Make sure you have communicated with the owning team before revoking a token that is actively in use.

Field reference

Name — A human-readable label for the token. Used to identify it in the list and on the detail form. Required. No length limit applies. Cannot be left blank.

Type — The integration context for the token. Must be either SCIM (for user provisioning via SCIM 2.0) or MCP (for AI assistant and Model Context Protocol access). Required. Locked permanently after the token is saved for the first time — you cannot change the type later.

Validity — How many days from today until the token expires. Choose one of the presets (182, 365, 548, or 731 days) or select Custom and enter your own number. Required. Custom values above 3,652 days are silently capped at 3,652. The expiration date is recalculated instantly whenever you change this field.

Custom validity — Appears only when you select Custom in the Validity dropdown. Enter a positive integer representing the number of days. Non-numeric characters are ignored. Zero or blank prevents the form from submitting.

Expiration date — Calculated automatically from today's date plus the chosen validity period. Read-only. Shown in UTC format.

Comment — Free-text notes about the token's purpose, the system it serves, the person who requested it, or a change-request reference. Optional. No length limit. Shown on the token's detail form and visible to auditors.

URL (MCP tokens only) — The MCP server endpoint that the AI client must connect to. Read-only and calculated automatically. Appears only when the token type is set to MCP. A copy icon lets you copy it to the clipboard with one click.

How this connects to the rest of DPMS

Tokens created on this screen are the authentication keys for two of the most important automated workflows in DPMS:

• SCIM user provisioning — The SCIM Overview screen (also under IAM) shows the SCIM base URL and provisioning endpoints. Those endpoints only accept requests that carry a valid SCIM-type bearer token generated here. Without one, your identity provider cannot create, update, or deactivate DPMS accounts automatically, and every user change must be made by hand.
• AI assistant and MCP-powered features — The AI helper buttons, automatic translation, and AI-driven risk scoring across DPMS all depend on the MCP server being reachable with a valid MCP-type token. Until you create one, those features produce authentication errors or remain unavailable entirely. The MCP server URL shown on the creation form is the direct endpoint your AI configuration needs.

Once you have created a SCIM token, your next step is usually the SCIM Overview screen to copy the provisioning base URL and configure your identity provider. Once you have created an MCP token, your next step is the AI settings area (or your external MCP client configuration) where you enter both the URL and the token.

The Notifications sub-screen under IAM lets you configure email alerts that fire a set number of days before a token expires. Setting up those alerts after creating a token is strongly recommended so you are never caught off guard by a sudden provisioning or AI failure caused by an unnoticed expiry.

Tips & common pitfalls

Heads up: The full token string is shown only once, on the reveal screen immediately after creation. Copy it before you navigate away. If you lose it, you must delete the token and create a new one — there is no way to retrieve it later.

Heads up: The confirmation toast that appears when you click Save for a new token will disappear on its own if you do not interact with it. If that happens, the token has not been created. Click Save again to trigger the toast a second time.

• The token type cannot be changed after creation. If you create a SCIM token and later realise you needed an MCP token (or vice versa), delete the original and start over with the correct type selected.
• Custom validity values above 3,652 days are silently reduced. If you type 5000, the form will store 3,652 without warning you. Always verify that the calculated Expiration date field shows the date you intended before clicking Save.
• Expired tokens do not disappear automatically. They accumulate on the Expired tab until an admin explicitly deletes them. Build a regular review habit — quarterly works for most teams — to keep your token inventory clean and defensible in an audit.
• Deleting an active token has immediate effect. There is no cooldown period. Any running integration that depends on the deleted token will fail instantly. Coordinate with system owners before revoking active credentials.
• The MCP server URL can be retrieved later even if you did not copy it at creation time. Open the token's detail form by clicking on its row — the URL field appears there for MCP-type tokens. Unlike the token secret itself, the URL is not a one-time display.