Skip to main content
Before the ACB API can be called, you need a Management Tool user configured for external application access. From Syteca 7.28, that user authenticates with a Client ID and a Client Secret using the OAuth 2.0 Client Credentials flow. This page covers creating the user and configuring both the current and the legacy authentication methods.
NOT AVAILABLE IN SAAS. This procedure applies to on-premises deployments only.
Refresh Token authentication is deprecated. It continues to work for three months after you update the Application Server, then stops. New installations of 7.28 and later cannot use it at all. See Migrate to Client ID / Client Secret authentication.

Two account types, two use cases

The ACB API can authenticate against two different account types in Syteca: Application Accounts can’t have administrative permissions like User Management — that’s intentional. To rotate the admin password, you need a regular Internal or AD user with that permission, and the same external-app toggle enabled.

Prerequisites

Without these three, the Automation tab won’t appear on the Edit Secret and Edit Folder pages — making secret IDs and folder IDs inaccessible.
The User Details tab, where both authentication methods are configured, is only accessible to users with the administrative User Management permission.

Create the user

1

Open the Users page

Sign in to the Management Tool as a user with the administrative User Management permission. Click Users in the left navigation.
2

Click Add User

Click the Add User button in the top right.
3

Pick the user type

Either add an Internal user or an Application Account user, or edit an existing Active Directory user.
For rotating the default admin user’s password, use an Internal or Active Directory user — Application Accounts can’t have the administrative User Management permission, which is required for the admin-password endpoints.
4

Configure user properties

Fill in the standard user fields (Login, password, etc.) as per the Add a user procedure.

Enable external application access

For an Internal or Active Directory user, the authentication sections only appear once you turn on the external-application toggle. For an Application Account, they are present by default.
1

Open the User Details tab

Open the user and go to the User Details tab.
2

Enable the toggle

In the Application Account Settings section, move the Allow this user account to be used by external applications toggle to the right.The Client ID / Client Secret authentication and Refresh Token-Based Authentication sections appear. Turning the toggle off hides both again.

Configure Client ID and Client Secret

Client ID field, Remove All link, Add Secret button, and the Client Secrets grid showing name, description, generated date and expiration date

The Client ID / Client Secret authentication section with two configured Client Secrets.

The Client ID

Each account gets one Client ID, generated automatically. It never changes and cannot be edited. Use the Copy icon to copy it.

The Client Secrets grid

An account can hold any number of Client Secrets. Remove All deletes every secret on the account.
Name uniqueness is scoped to what you can see. If a Client Secret with the same name exists but isn’t accessible to you, you can still create one with that name.

Add a Client Secret

1

Click Add Secret

In the Client ID / Client Secret authentication section, click Add Secret. The Add Client Secret window opens.
2

Name the secret

Name is required. Description is optional, up to 1000 characters. Name the secret after the system that will use it, so you know what breaks if you rotate it.
3

(Optional) Restrict by IP address

IP Address restriction limits this secret to specific addresses. Separate multiple addresses with a semicolon (;). Requests from any other address are rejected with 403 Forbidden.
4

Set the Access Token Lifetime

Access Token Lifetime (minutes) controls how long each issued Access Token stays valid. It is required, defaults to 15 minutes, and has a minimum of 1 minute.
This field is in minutes. The legacy Authorization token lifetime field in the Refresh Token section is in seconds. Both can be visible on this tab during the transition period.
5

Set the expiry date

Valid until defaults to today plus 30 days. The minimum validity period is 1 day and the maximum is 365 days. Pick a date with the calendar icon, or type it in the date format configured in the Management Tool.The secret stays valid until 23:59:59 on the selected date, in the Application Server’s time zone.
6

Save

Click Save. The Client Secret Generated window opens with the new secret.
The Client Secret is shown once and never again. Copy it from the Client Secret Generated window and store it in a secrets vault before closing. It is held in the database in encrypted form only, and nobody can retrieve it afterwards, including administrators. If you lose it, rotate the secret and update the consuming application.

Rotate, edit, and remove

Rotating a Client Secret invalidates the old one the moment the new one is generated. Update the consuming application in the same maintenance window, or its API calls start failing with 401 Unauthorized.

How requests are validated

Services using a Client Secret validate the secret itself, plus the IP Address restriction and the expiry date configured on it.

Account lockout

Authentication attempts with an invalid Client Secret count toward the account lockout threshold configured for the user, exactly as failed password attempts do in the Management Tool. Two lockout types behave differently:

Rate limiting

API requests authenticated with Client ID / Client Secret are rate limited per Client ID, not per secret or per token. Every request made with the same Client ID counts toward one quota, no matter how many Client Secrets or active Access Tokens the account holds.

Legacy: Refresh Token-based authentication

This method is deprecated. It stops working three months after you update the Application Server, and is unavailable on new 7.28 installations. See Migrate to Client ID / Client Secret authentication.
The Refresh Token is a long-lived credential exchanged for short-lived Access Tokens during API operation.
Refresh Token-Based Authentication section showing the deprecation note, Refresh Token field, Authorization token lifetime and IP Address restriction

The Refresh Token-Based Authentication section, with the deprecation note shown at the top.

1

Copy the Refresh Token

Click the Copy icon next to the Refresh Token field.
Treat the Refresh Token like a password. Anyone with this token can obtain Access Tokens and call the API on this user’s behalf. Store it in a secrets vault, not in source control or pipeline config.
2

(Optional) Set Authorization token lifetime

Authorization token lifetime (sec) controls how long Access Tokens stay valid.
3

(Optional) Restrict by IP address

The IP Address restriction field limits the API consumer to a specific IP address. Requests from any other IP return 403 Forbidden.
4

Save the user

Click Save to commit the changes.

What happens when the toggle is disabled

Disabling the Allow this user account to be used by external applications toggle:
  • Hides the Client ID / Client Secret and Refresh Token sections.
  • Expires the Refresh Token immediately. Any in-flight automation calling the API on behalf of this user starts failing with 401 Unauthorized.
Re-enabling the toggle generates a new Refresh Token — the old one is permanently invalid.

Where Client Secret activity is recorded

Token security events are written to C:\Program Files\Ekran System\Ekran System\Server.log at INFO level.
Each entry records the timestamp, the User ID or Client ID, the requested endpoint, the source IP address, the result, and the rejection reason where one applies.

Next steps

Migrate to Client ID / Client Secret

The transition period, what changes, and how to move each integration.

Secret permissions

Grant the user Owner / Editor / PAM User roles on specific secrets and folders.

Users page

Full reference for adding and editing Syteca users.

Administrative permissions

The permissions required for ACB API access.

API reference

Base URL, authentication, status codes.