Skip to main content

Entrust integration

The Entrust integration connects your automation or agent to Entrust Identity as a Service (IDaaS) using the Administration API. After you connect with an API application's credentials, you can look up users, create and update accounts, reset passwords, change activation state, unlock users, manage organizations, run paged searches, and (where your tenant supports it) sync users with a directory.

This page walks you from Entrust portal setup through field-by-field configuration and each supported action, so you can use the integration without guesswork.

What you can do​

AreaCapabilities
ReadGet user by UUID, by login userId, by externalId; list users with filters and paging (v4).
WriteCreate / update / delete one user or many; update multiple users in one call; modify organization membership.
Security & accessSet or reset password (temporary password and force change on next login); unlock account; set ACTIVE / INACTIVE.
DirectorySynchronize or unsynchronize a user with AD/LDAP (requires IDaaS directory + Gateway 5.0+).

All of this is backed by Entrust's Administration API; you interact through named actions in Yellow (for example Get user by UUID, Create a user), not by typing URLs.

Prerequisites​

Before you configure the integration in Yellow:

  1. Entrust IDaaS tenant with Administration API access as documented by Entrust for your environment.
  2. Administration API application created in the Entrust IDaaS Administration Portal under Applications (or equivalent in your portal).
  3. From that application, you will need:
    • Application ID
    • Shared secret
  4. Your tenant's API base URL exactly as Entrust provides it (scheme + host, and path prefix if your tenant uses one—no trailing slash).
  5. API permissions on the application must match what you intend to run. Missing access usually shows as 403 with a message such as USERS:VIEW required. See Required API permissions below.

Step 1: Create and scope the Administration API app (Entrust portal)​

  1. Sign in to the Entrust IDaaS Administration Portal.
  2. Open Applications (or your portal's equivalent) and create or select an Administration API application.
  3. Copy Application ID and shared secret into a secure location (password manager). Treat the shared secret like a password.
  4. Enable only the API permissions your flows need (principle of least privilege). Use the permission reference to match actions to scopes.
  5. Confirm the API base URL for your tenant (from Entrust documentation or your admin). Examples are tenant-specific; always use the value Entrust gives you.

Step 2: Configure the integration in Yellow​

  1. Open your Integrations (or App configuration) area and add Entrust.
  2. Fill in the three required fields:
FieldWhat to enterTips
API base URLFull base URL for your tenant's APINo trailing /. Wrong host or unreachable URL causes connectivity errors.
Application IDFrom the Administration API applicationPasted exactly; no extra spaces.
Shared secretFrom the same applicationNever commit to source control or share in plain chat.
  1. Access token is managed for you: after a successful sign-in, Yellow keeps the session token and uses it automatically for each action. You do not need to paste or refresh a token by hand under normal use.
  2. Click Connect (or your product's Save / Verify). Yellow checks your Application ID and shared secret with Entrust. On success you should see that Entrust Administration API credentials verified; after that, your flows can run the actions below.

Validation behavior​

  • Success: You should see a message that Entrust Administration API credentials verified.
  • Failure (401): Usually wrong Application ID or shared secret. Re-copy from the portal and try again.
  • Unreachable host (ENOTFOUND or similar): Check API base URL (typo, wrong region, VPN, or DNS).

Authentication and token refresh​

  • Signing in: The first time you connect—and whenever needed—Yellow signs in to Entrust using your Application ID and shared secret stored in the integration.
  • Running actions: You only pick an action and fill its fields; Yellow attaches the active session automatically.
  • If the session expires: A 401 / "authentication failed or token expired" style error usually triggers a fresh sign-in in the background. If problems persist, reconnect from the integration card and confirm the app is still enabled in the Entrust portal.

Required API permissions​

Grant your Administration API application only what you need. The integration surfaces friendly errors that name the permission when Entrust returns 403.

PermissionTypical actions
USERS:VIEWGet user by UUID / userId / external ID; List a page of users; read-style responses.
USERS:ADDCreate a user; Create multiple users.
USERS:EDITUpdate a user; Update multiple users; Modify user organization; Update user state; Unlock user; Synchronize user; Unsynchronize user.
USERS:REMOVEDelete a user; Delete multiple users.
USERPASSWORDS:EDITSet temporary password (reset password endpoint).

If an action fails with Insufficient permissions (... required), add that scope in the Entrust portal for the same API application, then reconnect or retry.

Field conventions: what goes where​

Some actions ask for User UUID only as a separate field (used to identify the account). Do not repeat that UUID in the extra payload fields unless the form explicitly asks for it there too.

  • User UUID as its own field (not duplicated in the payload): get by UUID, set password, update state, unlock, update user, delete user, modify organization.
  • User ID in the payload: Get user by user ID uses the login userId in the request body. Get user by external ID is special—the form still uses a field labeled for external ID, but Entrust expects it under the property name userId in the body (see that section below).

Actions (configuration and usage)​

For each action, fill the required fields in your flow or integration step. Optional fields can be left empty unless you need them. Simple examples below are illustrative—use real values from your tenant.

Typical wait times: Lookups and small updates usually finish in a few seconds. Creating or updating users, bulk jobs, directory sync, and large paged lists may take longer (up to about a minute in heavy cases).

Get user by UUID​

  • Purpose: Fetch a single user by internal UUID.
  • Required: User UUID (the Entrust internal id for that person).
  • Permissions: USERS:VIEW (typical).
  • Success data (illustrative): id, userId, state, locked, email, firstName, lastName, … (exact fields per Entrust API version).
  • Errors: 401 → authentication failed or token expired; 404 → user not found.

Get user by user ID​

  • Purpose: Lookup by login userId (username).
  • Required: User ID (the username / login id the person uses to sign in).
  • Permissions: USERS:VIEW.
  • Errors: 401, 404 (user not found).

Get a user by external ID​

  • Purpose: Lookup by external ID stored on the user (often the id from your HR or source system).
  • Important: This is not the same as Get user by user ID (login name). Use the action meant for external ID and enter the id from your other system.
  • Required: The external ID value to look up.
  • Permissions: USERS:VIEW.
  • Errors: 401, 403, 404.

List a page of users​

  • Purpose: Search the user directory one page at a time. If you add several search rules, Entrust treats them as AND (all must match).
  • Required: Nothing—everything below is optional.
  • Optional fields:
    • Page size (limit): How many users per page (1–100).
    • Cursor: Copy from the previous response to fetch the next page. When you use a cursor, search and sort options are ignored for that call—use the cursor alone to continue paging.
    • Search filters: List of rules; each rule has an attribute name, an operator (such as equals, contains, greater than, "in list", exists / not exists, and others), and usually a value. Which operators work on which attributes is defined by Entrust—use their Administration API documentation for the full matrix. Common filter names include userId, state, locked, organizationId, lastAuthTime, and more.
    • Sort: Sort field (often userId, state, or lastAuthTime) and ascending / descending.
    • Extra data per user: Optional add-ons such as groups, roles, tokens, aliases, organizations, etc., depending on what your tenant supports.
  • Permissions: USERS:VIEW.
  • Errors: 400 invalid search/limit/paging; 401; 403 with USERS:VIEW required message when permission missing.

Create a user​

  • Purpose: Create one user.
  • Required: First name, Last name, Email, User ID (the login id you want in Entrust).
  • Optional (examples—you can add as many as your form offers): grace period, verification email, external id/source, groups and organizations, locale, phone and mobile, OTP delivery preference (EMAIL, SMS, VOICE, or SYSTEM), registration / verification flags, ACTIVE / INACTIVE state, security id, aliases, and extended attribute blocks. Use Entrust's docs for advanced attribute shapes.
  • Permissions: USERS:ADD.
  • Errors: 401; 403 USERS:ADD required; 400 validation; 409 user ID or alias already exists.

Update a user​

  • Purpose: Update profile and related fields for one user.
  • Required: User UUID of the account to change, plus whichever profile fields you are updating.
  • Optional fields: Same kinds of details as Create a user (email, names, groups, organizations, state, OTP preferences, and so on). User ID (login) can be changed on update only if your process requires it—it is not required every time.
  • Permissions: USERS:EDIT.
  • Errors: 401; 403 USERS:EDIT required; 400; 404 not found; 409 user ID or alias conflict.

Delete a user​

  • Purpose: Delete one user by UUID.
  • Required: User UUID of the account to remove.
  • Permissions: USERS:REMOVE.
  • Errors: 401; 403 USERS:REMOVE required; 404.

Modify user organization​

  • Purpose: Replace the user's organization membership with the given list.
  • Required: User UUID; Organizations (list of organization UUIDs the user should belong to after the change).
  • Permissions: USERS:EDIT.
  • Errors: 401; 403; 404.

Set temporary password​

  • Purpose: Set password for a user; control temporary flag and forced change on next login.
  • Required: User UUID; New password; whether it is a temporary password; whether to force change on next login.
  • Note: Enter the User UUID in its own field; fill password and flags only in their dedicated fields—do not duplicate the UUID inside the password payload.
  • Permissions: USERPASSWORDS:EDIT.
  • Errors: 401; 403 USERPASSWORDS:EDIT required.

Update user state​

  • Purpose: Set account state to ACTIVE or INACTIVE.
  • Required: User UUID; State (ACTIVE or INACTIVE).
  • Permissions: USERS:EDIT.
  • Errors: 401; 403 USERS:EDIT required; 404.

Unlock user​

  • Purpose: Unlock a locked user account.
  • Required: User UUID of the account to unlock.
  • Permissions: USERS:EDIT.
  • Errors: 401; 403; 404.

Create multiple users​

  • Purpose: Create many users in one request.
  • Required: A users list. Each person usually needs at least first name, last name, email, and user ID (your tenant may require more—match what you use for Create a user). You can add the same optional details as when creating one user.
  • Optional: Stop on error—when on, stop after the first failed row; when off, keep trying the rest (default is off if you leave it unset).
  • Permissions: USERS:ADD.
  • Errors: 401; 403; 400 validation on one or more items; 409 duplicate user ID or alias.

Update multiple users​

  • Purpose: Batch update different users in one call.
  • Required: A users list. Each row must include:
    • Id: The value that identifies the person (see Id type).
    • Id type: UUID (internal id), USERID (login id), or EXTERNALID. If you skip this, Entrust usually treats Id as a UUID.
    • Changes: Only the profile fields you want to change for that person; every field inside this block is optional—omit what should stay the same.
  • Optional: Stop on error (default off). When on, the batch stops at the first failure; when off, remaining users are still attempted.
  • Changes supports the same kinds of fields as Update a user (email, names, state, groups, organizations, OTP preferences, and so on).
  • Permissions: USERS:EDIT.
  • Errors: 401; 403 USERS:EDIT required; 400 invalid request or validation failures.

Delete multiple users​

  • Purpose: Batch delete users.
  • Required: A users list; each row needs an Id. Id type is optional (UUID, USERID, or EXTERNALID; if omitted, Id is usually treated as a UUID).
  • Optional: Stop on error (same meaning as in other bulk actions).
  • Permissions: USERS:REMOVE.
  • Errors: 401; 403; 400.

Synchronize user​

  • Purpose: Sync a user with AD/LDAP via IDaaS (requires directory + Gateway 5.0+ in your environment).
  • Required: Directory ID (the directory's UUID in Entrust); User id (the internal UUID or login id, depending on Id type below).
  • Optional: Id type—UUID or USERID only (external ID is not supported here). If you leave it out, Entrust usually assumes USERID.
  • Permissions: USERS:EDIT.
  • Errors: 401; 403; 400 invalid directory, user id, or sync configuration.

Unsynchronize user​

  • Purpose: Remove AD sync so the user becomes locally managed; re-enable sync with Synchronize user later.
  • Required: User id (internal UUID or login id, depending on Id type).
  • Optional: Id type—UUID or USERID only (defaults to USERID); external ID is not supported here.
  • Permissions: USERS:EDIT.
  • Errors: 401; 403; 400 invalid user or unsync not allowed.

Shared field reference (create, update, and bulk "changes" blocks)​

Use the same values across Create a user, Update a user, and the per-user changes section in Update multiple users:

  • locale: da, de, en, es, fr, it, ja, ko, nl, nb, pl, pt, ru, sv, th, tr, zh-cn, zh-tw.
  • preferredOtpDelivery: EMAIL, SMS, VOICE, SYSTEM.
  • state: ACTIVE, INACTIVE.
  • Arrays: groups, oauthRoles, organizations expect UUID strings unless your tenant documentation specifies otherwise.
  • Complex: userAliases, userAttributeValues, userExtraAttributes, preferredOtpDeliveryContactAttributes follow Entrust's object shapes. When in doubt, copy structure from an existing user you exported from Entrust or from Entrust's own Administration API guides.

Error handling (what you will see)​

Integration-level (connect / network)​

  • API base URL not reachable (host not found / connection errors): Fix URL, DNS, VPN, or firewall; ensure no trailing slash on base URL.
  • Authentication failed (401) on connect: Wrong Application ID or shared secret—re-verify in the Administration Portal.

Action-level (common error codes)​

CodeTypical meaningWhat to do
401Session or credentials problemReconnect from the integration card or retry; Yellow may renew the session automatically.
403Missing Entrust permissionAdd the named permission to the API application in Entrust.
404User not foundCheck User UUID, login User ID, Id type in bulk actions, or use the correct lookup action.
400Invalid or incomplete requestFix required fields, allowed values, or filters.
409ConflictDuplicate User ID or alias when creating or updating.

If a message hints at your credentials or integration settings, fix those first; if it points to bad or missing user data, adjust the fields you passed into the action.

Best practices​

  1. Least privilege: Start with read-only scopes; add USERS:ADD, USERS:EDIT, USERS:REMOVE, or USERPASSWORDS:EDIT only when needed.
  2. Secrets: Rotate shared secrets in Entrust if exposed; update the integration immediately after rotation.
  3. Base URL: Copy from Entrust docs or admin UI; avoid guessing regional hostnames.
  4. Bulk operations: Use stopOnError: true when you need all-or-nothing semantics; use false for best-effort partial success (confirm behavior with Entrust response bodies in your environment).
  5. Paging: For large directories, use List a page of users with limit and cursor rather than assuming a single response returns everyone.
  6. External ID lookup: Use the external ID value in the action meant for that lookup; do not confuse it with the login user ID action.

Troubleshooting checklist​

  1. Connect fails immediately → Check API base URL (reachable, no trailing slash), Application ID, shared secret.
  2. 403 on a specific action → Compare action to permission table; update Entrust app scopes.
  3. 404 on get → Wrong UUID or wrong Id type in bulk updates; for external lookup, use Get user by external ID and the value from your source system.
  4. 409 on create/update → User ID or alias collision; pick a unique userId or adjust aliases.
  5. 400 on list users → Invalid limit (must be 1–100), invalid filter combination, or cursor used together with incompatible search options.
  6. Sync / unsync errors → Confirm directory ID, Gateway version, and that EXTERNALID is not used on sync endpoints.

Summary​

Configure API base URL, Application ID, and shared secret from an Entrust Administration API application, then Connect so Yellow can sign in and keep the session for you. Pick actions that match the permissions you enabled in Entrust, use User UUID only where the form asks for it, and use Get user by external ID (not login lookup) when you have an external system id. Use bulk and List a page of users when you have many accounts. For unusual profile fields, rely on Entrust's Administration API documentation together with the field lists above.