> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Client ID / Client Secret Authentication

> Move ACB API integrations from Refresh Token authentication to the OAuth 2.0 Client Credentials flow before the three-month transition period ends.

From Syteca 7.28, the ACB API authenticates with a **Client ID** and a **Client Secret** using the OAuth 2.0 Client Credentials flow. Refresh Token authentication still works for three months after you update the Application Server, then stops. This page covers what changes, when, and what to do about it.

<Warning>
  **NOT AVAILABLE IN SAAS.** This applies to **on-premises** deployments only.
</Warning>

## Who this affects

Everything that calls the ACB API with a Refresh Token: CI/CD pipelines, scripts, SOAR playbooks, CMDB integrations, external secrets vaults, and any use of the ACB Console CLI that passes a token.

It applies to **Application Accounts, Internal users, and Active Directory users** with the external-application toggle enabled.

## The timeline

<Note>
  The transition period runs for **three months from the date you update the Application Server**, not from the release date. The expiry date set on each Refresh Token is stored in the database and is **not displayed in the Management Tool**, so calculate your deadline from your own update date.
</Note>

| Stage | Refresh Token | Client ID / Client Secret |
| - | - | - |
| Before you update | Works | Not available |
| During the three-month transition | Works | Works |
| After the transition ends | Rejected | Works |
| New 7.28 installation, no prior version | Never available | Works |

### What happens when the transition ends

* Requests sent with an expired Refresh Token are rejected.
* Every field in the **Refresh Token-Based Authentication** section is disabled: **Refresh Token**, **Authorization token lifetime (sec)**, and **IP Address restriction**.
* The ACB Console CLI accepts only Bearer access tokens. Refresh Token authentication is no longer supported there.

### Clean installations

If you install 7.28 or later on a server that never ran an earlier version, there is no transition period. Refresh Token authentication is unavailable from the start: the fields are disabled and not editable, Refresh Tokens can't be generated, regenerated, or modified, and API requests using them are rejected.

## Warnings you will see

The Transaction Log on the [System Health dashboards](/docs/administration/dashboards/system-health-dashboards) records the migration for you.

| Record | When it appears |
| - | - |
| Refresh Token expiry warning | 30, 14, 7, and 1 day before the token's expiration date |
| Deprecated endpoint use | Each time an integration calls the deprecated access token endpoint |
| Client Secret expiry warning | Before a Client Secret expires, so a rotation doesn't catch you out |

Because the Refresh Token expiry date isn't shown in the Management Tool, the 30-day warning is your first in-product signal. Don't wait for it: if you updated the server, you already know the deadline.

## Migrate an integration

Work through this once per integration. During the transition both methods work, so you can migrate them one at a time and roll back if something breaks.

<Steps>
  <Step title="List what uses the Refresh Token">
    Check the Transaction Log for deprecated endpoint records. Each one names the account making the call, which tells you what still needs migrating.
  </Step>

  <Step title="Create a Client Secret for the integration">
    Open the account on the **Users** page, go to the **User Details** tab, and add a Client Secret in the **Client ID / Client Secret authentication** section. Name it after the integration that will use it. See [Set up a user account](/docs/api/acb/setup-user-account) for the field reference.

    Give each integration its own Client Secret rather than sharing one. Rotating a shared secret breaks everything that holds it.
  </Step>

  <Step title="Copy the Client ID and the Client Secret">
    The Client Secret is displayed once, in the **Client Secret Generated** window. Copy it into your secrets vault before closing the window.
  </Step>

  <Step title="Carry over the IP restriction and token lifetime">
    If the Refresh Token had an IP Address restriction, set the same restriction on the Client Secret. Set **Access Token Lifetime** to suit the integration, remembering that it is in **minutes** here and the legacy field was in **seconds**.
  </Step>

  <Step title="Update the integration">
    Change the integration to request an access token with its Client ID and Client Secret, then send that token in the **Authorization** header using the **Bearer** scheme. For the ACB Console CLI, pass `--token_type Bearer`; without it, the CLI falls back to the legacy Refresh Token behaviour.
  </Step>

  <Step title="Test, then confirm the old path is unused">
    Run the integration and confirm it works. Then watch the Transaction Log: once no more deprecated endpoint records appear for that account, the migration is done.
  </Step>
</Steps>

## Things worth knowing before you plan

<AccordionGroup>
  <Accordion title="Access tokens are invalidated when the ACB service restarts">
    If the service is restarted, every access token issued before the restart becomes invalid, and integrations must request a new one with their Client ID and Client Secret. Build token re-request into your error handling rather than caching a token for its full lifetime and assuming it holds.
  </Accordion>

  <Accordion title="Obtaining a new token doesn't invalidate the old one">
    If an account obtains a second access token, or the user signs in to the Management Tool, the first access token stays valid for its configured lifetime. Tokens expire on their own schedule.
  </Accordion>

  <Accordion title="Invalid Client Secrets count toward account lockout">
    Authentication attempts with an invalid Client Secret are treated as failed authentication attempts and count toward the account's lockout threshold, the same as failed passwords. An integration retrying with a stale secret can lock the account.
  </Accordion>

  <Accordion title="Rotation invalidates the old secret immediately">
    There is no grace period. The moment a new secret is generated, the previous one stops working. Rotate and deploy in the same window.
  </Accordion>

  <Accordion title="Client Secrets expire, and the maximum is 365 days">
    Unlike Refresh Tokens, Client Secrets carry an expiry date, with a maximum validity of 365 days. Migration isn't a one-off: put secret rotation into your normal operational schedule and use the Transaction Log warnings as the backstop, not the plan.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| What you see | Check |
| - | - |
| **401 Unauthorized** after a rotation | The integration is still using the old Client Secret. The previous secret is invalid as soon as a new one is generated. |
| **401 Unauthorized** with no recent change | The Client Secret has passed its **Valid until** date, or the transition period has ended and the integration is still using a Refresh Token. |
| **403 Forbidden** | The calling IP address isn't in the Client Secret's IP Address restriction. |
| The account keeps locking | An integration is retrying with an invalid Client Secret. Those attempts count toward the lockout threshold. |
| CLI commands fail after migration | `--token_type Bearer` is missing. Without it, the CLI uses the legacy Refresh Token path. |

## Related

<CardGroup cols={2}>
  <Card title="Set up a user account" icon="user-plus" href="/docs/api/acb/setup-user-account">
    Create the account and configure Client ID / Client Secret authentication.
  </Card>

  <Card title="System Health dashboards" icon="activity" href="/docs/administration/dashboards/system-health-dashboards">
    The Transaction Log, where expiry and deprecation warnings appear.
  </Card>

  <Card title="Audit log" icon="scroll-text" href="/docs/administration/audit-log">
    The record of Client Secrets added, edited, rotated, and removed.
  </Card>

  <Card title="ACB CLI" icon="terminal" href="/docs/api/acb/cli">
    Console commands and the token type parameter.
  </Card>

  <Card title="API reference" icon="square-code" href="/docs/api/acb/api-reference">
    Base URL, authentication, status codes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.