> ## 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.

# Syteca ACB API Reference

> The Syteca ACB REST API reference — base URL, two authentication models (old vs new endpoints), status codes, rate limiting per endpoint, and the complete endpoint list.

The ACB exposes its functionality through a REST API at a single base URL, authenticated with a per-user Refresh Token that's exchanged for short-lived Access Tokens. This page covers everything that's shared across endpoints — base URL, authentication mechanics, status codes, rate limits. Per-endpoint detail lives on each [endpoint page](#endpoints).

<Warning>
  **NOT AVAILABLE IN SAAS.** ACB is on-premises only.
</Warning>

## Base URL

All endpoints share the same base URL:

```text theme={"system"}
https://<hostname>/SytecaACB
```

Replace `<hostname>` with the computer name where the ACB service is installed.

<Warning>
  **For ACB deployments updated from a version prior to 1.2**, the URL prefix is `EkranACB` instead of `SytecaACB`. Use `https://<hostname>/EkranACB/...` exactly in scripts targeting those installs.
</Warning>

## Authentication

ACB uses a two-step authentication model: a long-lived **Refresh Token** is exchanged for a short-lived **Access Token**, and the Access Token authenticates subsequent API calls.

### 1. Get the Refresh Token

The Refresh Token is generated per user in the Management Tool — see [Set up user account](/docs/api/acb/setup-user-account) for the procedure. Once you have it, store it securely (treat it like a password).

### 2. Exchange Refresh Token for Access Token

Call [`POST /SytecaACB/get_access_token`](/docs/api/acb/endpoints/get-access-token) with the Refresh Token in the JSON body. The response includes the **Access Token** and its `expires_in` lifetime (in seconds).

### 3. Use the Access Token on subsequent calls

The authentication mechanism differs between old and new endpoints:

| Endpoint generation                                                   | How to pass the Access Token                       |
| --------------------------------------------------------------------- | -------------------------------------------------- |
| **New endpoints** *(v1.3+ — folders, secrets, bulk, user management)* | `Authorization` header with the Access Token value |
| **Old endpoints** *(`get_access_token` and `get_secret_details`)*     | `accessToken` field in the JSON request body       |

<ParamField header="Authorization" type="string">
  *(New endpoints only)* The Access Token returned by `get_access_token`. Format: pass the raw token value as the header value.
</ParamField>

<Note>
  When the Access Token expires (default: 600 seconds — see [Authorization token lifetime](/docs/api/acb/setup-user-account)), call `get_access_token` again with the same Refresh Token to get a new one. Refresh Tokens themselves only expire if the user's [external-app toggle is disabled](/docs/api/acb/setup-user-account#what-happens-when-the-toggle-is-disabled).
</Note>

## Status codes

| Code    | Name                  | Description                                                                                                                                                                                                         |
| ------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **200** | OK                    | Successful request returning data.                                                                                                                                                                                  |
| **201** | Created               | Resource (folder, secret, user) created successfully.                                                                                                                                                               |
| **204** | No Content            | Successful action without response body (e.g. delete, rotate, force check-in).                                                                                                                                      |
| **400** | Bad Request           | Invalid input parameter. Response body indicates which one and why.                                                                                                                                                 |
| **401** | Unauthorized          | Missing, invalid, or expired Access Token. Re-issue a token from `get_access_token`.                                                                                                                                |
| **403** | Forbidden             | Authenticated user lacks the role required for this resource — e.g. trying to delete a secret with only PAM User role. Also returned when [IP Address restriction](/docs/api/acb/setup-user-account) blocks the request. |
| **404** | Not Found             | The requested resource (secret, folder, user) does not exist or is not visible to the authenticated user.                                                                                                           |
| **409** | Conflict              | Resource state conflicts with the request — e.g. trying to add a user with a duplicate login.                                                                                                                       |
| **422** | Unprocessable Entity  | Request is syntactically valid but semantically rejected — e.g. an AD domain user link references an unknown domain.                                                                                                |
| **429** | Too Many Requests     | Rate limit exceeded. See [Rate limiting](#rate-limiting).                                                                                                                                                           |
| **500** | Internal Server Error | The Application Server is not working as expected. Try again later.                                                                                                                                                 |
| **503** | Service Unavailable   | The Application Server is probably stopped.                                                                                                                                                                         |

## Rate limiting

Different endpoint groups have different rate limits. Exceeding the limit returns **HTTP 429 Too Many Requests** with a `Retry-After` header indicating when to retry.

| Endpoint group                                                                        | Rate limit                              |
| ------------------------------------------------------------------------------------- | --------------------------------------- |
| **Authentication** (`get_access_token`)                                               | 5 requests per minute per Refresh Token |
| **Secret retrieval** (`get_secret_details`, `get-secret`, `get-secret-credentials`)   | 60 requests per minute per Access Token |
| **Folder operations** (get/add/update/delete folder)                                  | 30 requests per minute per Access Token |
| **Secret modifications** (add/update/delete secret, rotate, force-checkin, heartbeat) | 30 requests per minute per Access Token |
| **Bulk add**                                                                          | 5 requests per minute per Access Token  |
| **User Management endpoints**                                                         | 30 requests per minute per Access Token |
| **Admin password rotation**                                                           | 5 requests per minute per Access Token  |

<Note>
  Rate limits are evaluated per Access Token, which is per Refresh Token, which is per Management Tool user. Multiple parallel automation consumers sharing one user account share the same rate budget.
</Note>

## Endpoints

### Old endpoints (pre-v1.3, still supported)

| Endpoint                                                                 | Method | Returns                                |
| ------------------------------------------------------------------------ | ------ | -------------------------------------- |
| [`/SytecaACB/get_access_token`](/docs/api/acb/endpoints/get-access-token)     | POST   | Access Token from Refresh Token        |
| [`/SytecaACB/get_secret_details`](/docs/api/acb/endpoints/get-secret-details) | POST   | Secret credentials (legacy auth model) |

### Folder endpoints

| Endpoint                                                          | Method | Returns              |
| ----------------------------------------------------------------- | ------ | -------------------- |
| [`/SytecaACB/api/folders/{id}`](/docs/api/acb/endpoints/get-folder)    | GET    | Folder details       |
| [`/SytecaACB/api/folders`](/docs/api/acb/endpoints/add-folder)         | POST   | Newly-created folder |
| [`/SytecaACB/api/folders/{id}`](/docs/api/acb/endpoints/update-folder) | PATCH  | Updated folder       |
| [`/SytecaACB/api/folders/{id}`](/docs/api/acb/endpoints/delete-folder) | DELETE | 204 No Content       |

### Secret endpoints

| Endpoint                                                                                          | Method | Returns                                      |
| ------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------- |
| [`/SytecaACB/api/secrets/{id}`](/docs/api/acb/endpoints/get-secret)                                    | GET    | Secret details (no password)                 |
| [`/SytecaACB/api/secrets/{id}/password`](/docs/api/acb/endpoints/get-secret-credentials)               | GET    | Secret credentials (with password / SSH key) |
| [`/SytecaACB/api/secrets`](/docs/api/acb/endpoints/add-secret)                                         | POST   | Newly-created secret                         |
| [`/SytecaACB/api/secrets/{id}`](/docs/api/acb/endpoints/update-secret)                                 | PATCH  | Updated secret                               |
| [`/SytecaACB/api/secrets/{id}`](/docs/api/acb/endpoints/delete-secret)                                 | DELETE | 204 No Content                               |
| [`/SytecaACB/api/secrets/{id}/rotate-secret-password`](/docs/api/acb/endpoints/rotate-secret-password) | POST   | 204 No Content                               |
| [`/SytecaACB/api/secrets/{id}/force-checkin`](/docs/api/acb/endpoints/force-checkin)                   | POST   | 204 No Content                               |
| [`/SytecaACB/api/secrets/{id}/heartbeat`](/docs/api/acb/endpoints/heartbeat)                           | POST   | Password check status (NEW in v1.4)          |

### Bulk action

| Endpoint                                                                     | Method | Returns                                         |
| ---------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
| [`/SytecaACB/api/bulk/add-secrets-and-folders`](/docs/api/acb/endpoints/bulk-add) | POST   | Summary of created folders, secrets, and errors |

### User Management and Admin Password Rotation

User Management endpoints (9) and Admin Password Rotation endpoints (2) — covered in Phase 2 of this batch, navigation links to come.

## Related

<CardGroup cols={2}>
  <Card title="Overview" icon="key-square" href="/docs/api/acb/overview">
    What the ACB API is and when to use it.
  </Card>

  <Card title="Data models" icon="braces" href="/docs/api/acb/data-models">
    Schemas shared across request and response bodies.
  </Card>

  <Card title="Set up user account" icon="user-plus" href="/docs/api/acb/setup-user-account">
    Configure a user with the Refresh Token.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/docs/api/acb/cli">
    SytecaACBConsole.exe — command-line wrapper.
  </Card>
</CardGroup>