> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pam/reference/api.md).

# API

Where the API specification lives, the three ways a client authenticates, the conventions every endpoint shares, and what each endpoint family covers.

## What this is and when to use it

The solution exposes a REST API over HTTPS. The console is itself a client of it: every screen you use is calling the same endpoints an external system would, which is why anything the console can do is reachable programmatically.

Use it to register assets from a CMDB, retrieve a credential inside a pipeline, export audit records into a data warehouse, or drive onboarding and offboarding from an identity system.

## Where the specification lives

Two addresses on your own instance, both generated from the version actually running:

| Address                                    | What it is                | Use it for                           |
| ------------------------------------------ | ------------------------- | ------------------------------------ |
| `https://<your-instance>/api/docs`         | Interactive documentation | Browsing endpoints and trying a call |
| `https://<your-instance>/api/swagger.json` | OpenAPI 2.0 specification | Generating a client in any language  |

{% hint style="info" %}
Read the specification from **your own instance** rather than any list written down elsewhere. It matches the build you are integrating with, which a wiki page cannot promise.
{% endhint %}

Every endpoint sits under the `/api/v1/` prefix, and the API answers over HTTPS only. A client that cannot validate the instance's certificate fails at the transport layer before authentication matters, so a self-signed certificate has to be trusted by the calling machine first.

## How a client authenticates

There is no anonymous access. Three mechanisms are available, and they carry different identities.

| Mechanism                             | Identity       | How the credential is obtained                                  |
| ------------------------------------- | -------------- | --------------------------------------------------------------- |
| **Access key signature**              | A console user | **Profile › Access keys**, which issues an ID and a secret      |
| **Integration application signature** | An application | Registered by an administrator, which issues an ID and a secret |
| **Bearer token**                      | A console user | `POST /api/v1/authentication/auth/` with username and password  |

### Signing a request

Both signature mechanisms use HTTP Signature with HMAC-SHA256. The client builds a signing string from the request target and the date, signs it with its secret, and sends the result in the `Authorization` header.

```
(request-target): get /api/v1/assets/hosts/?limit=10
date: Wed, 23 Sep 2026 20:44:35 GMT
```

```
Authorization: Signature keyId="<id>",algorithm="hmac-sha256",
               headers="(request-target) date",signature="<base64>"
Date: Wed, 23 Sep 2026 20:44:35 GMT
```

Three details decide whether the call succeeds:

* **The query string is part of the signing string.** Sign the request target exactly as it will be sent, parameters included and in the same order.
* **The date must be RFC 7231, in English, in GMT.** A client running on a machine with a non-English locale that formats the date in its own language produces a header the server rejects. This is the most common integration failure, and it only appears outside English-speaking environments.
* **An integration application adds `X-Source: datadike-pam`.** That header is what distinguishes an application from a user's access key, and without it the request is interpreted as the latter.

### Bearer token

A token obtained from the login endpoint is sent as `Authorization: Bearer <token>`. It carries the permissions of the user it was issued to and is short-lived, which makes it suitable for an interactive script and unsuitable for an unattended job. For anything that runs without a person present, prefer a signature.

{% hint style="warning" %}
An access key carries the full permissions of the user who owns it, so it is as powerful as that person's role. An integration application, by contrast, is scoped twice over: to the accounts it may read and to the source addresses it may call from. **For machine access, prefer an integration application.**
{% endhint %}

### Ready-made clients

The product ships a working client and its documentation for six languages, served by the instance itself under the integration application's **SDKs** tab. Each one implements the signing described above.

| Language   | Dependencies                |
| ---------- | --------------------------- |
| Python     | `requests`, `httpsig`       |
| Java       | None. Standard library only |
| Go         | None. Standard library only |
| Node.js    | `axios`                     |
| PowerShell | None. Built-in cmdlets only |
| curl       | None                        |

## Conventions every endpoint shares

### Pagination

Collections are paginated with `limit` and `offset`, and answer with a consistent envelope:

```json
{ "count": 412, "next": "...", "previous": null, "results": [] }
```

### Searching, ordering and filtering

| Parameter    | What it does                                                       |
| ------------ | ------------------------------------------------------------------ |
| `search`     | Free-text search across the resource's searchable fields           |
| `order`      | Field to sort by. Prefix with `-` to reverse                       |
| *field name* | Exact-match filter. Which fields are filterable varies by resource |

### Discovering a resource's fields

An `OPTIONS` request to a collection returns the resource's field metadata: names, types, whether each is required, and the available choices. It is the fastest way to learn a payload without reading the whole specification, and it reflects your own permissions.

### Export formats

Collections render as JSON, CSV or XLSX. Add `format=csv` or `format=xlsx` to a `GET`, and the response carries a header row with the same column names the console exports.

### Language

Responses honour the `Accept-Language` header and report what they used in `Content-Language`. Error messages, field labels and validation text come back translated.

| Sent    | Returned                                               |
| ------- | ------------------------------------------------------ |
| `en`    | `Authentication credentials were not provided.`        |
| `pt-br` | `As credenciais de autenticação não foram fornecidas.` |
| `es`    | `Las credenciales de autenticación no se proveyeron.`  |
| `fr`    | `Informations d'authentification non fournies.`        |

For a call authenticated as a console user, that user's own language preference takes precedence over the header.

### Organisations

An instance can hold several organisations, and most resources belong to one. Requests carry the organisation in the `X-PAM-ORG` header. A client that omits it operates in the default organisation, which is a common cause of a call succeeding and returning nothing.

## Endpoint families

Every family below is covered by the specification on your instance. The operation counts are a measure of surface, not of importance.

| Family                  | Prefix             | Operations | What it covers                                                                     |
| ----------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------- |
| Sessions and connectors | `/terminal/`       | 249        | Live sessions, recordings, connection endpoints, applets, publishing hosts         |
| Assets                  | `/assets/`         | 229        | Hosts, databases, devices, cloud, platforms, nodes, zones, discovery               |
| Accounts                | `/accounts/`       | 159        | Managed accounts, templates, rotation, discovery, backup, integration applications |
| Authentication          | `/authentication/` | 100        | Login, MFA, access keys, SSH keys, passkeys, connection tokens                     |
| Tickets                 | `/tickets/`        | 96         | Access requests, approval flows, approvers                                         |
| Authorizations          | `/perms/`          | 77         | Who may reach which asset with which account                                       |
| Roles and permissions   | `/rbac/`           | 75         | Roles, role bindings, the permission catalogue                                     |
| Users                   | `/users/`          | 70         | Users, groups, directory synchronisation                                           |
| Automation              | `/ops/`            | 64         | Jobs, ad-hoc commands, playbooks, execution history                                |
| Access control          | `/acls/`           | 58         | Command filters, login rules, connection method rules                              |
| Gateways                | `/brokers/`        | 37         | Reverse gateways and the targets reachable through them                            |
| Labels                  | `/labels/`         | 34         | Labels and what carries them                                                       |
| Audit                   | `/audits/`         | 28         | Login records, operation logs, credential retrievals, file transfers               |
| Notifications           | `/notifications/`  | 26         | Channels, subscriptions, message templates                                         |
| Settings                | `/settings/`       | 25         | System configuration                                                               |
| Behaviour analysis      | `/ueba/`           | 20         | Behavioural findings and their rules                                               |
| Reports                 | `/reports/`        | 19         | Report definitions, runs, downloads                                                |
| Vault                   | `/vault/`          | 16         | Credentials kept and shared by hand, in folders                                    |
| Organisations           | `/orgs/`           | 12         | Tenants and their membership                                                       |

## Errors

Failures answer with a JSON body carrying a human-readable `detail` and a stable `code`:

```json
{ "detail": "Authentication credentials were not provided.", "code": "not_authenticated" }
```

| Status | Usual cause                                                                 |
| ------ | --------------------------------------------------------------------------- |
| 400    | A payload that failed validation. The body names the offending fields       |
| 401    | No credential, an expired token, or a signature the server could not verify |
| 403    | A valid identity without permission for this resource                       |
| 404    | The resource does not exist, or belongs to another organisation             |

Match on `code` rather than on `detail`, because `detail` is translated and `code` is not.

## How to verify you can reach the API

Three checks, in the order that finds problems fastest:

1. **Call the health endpoint.** It needs no credential, which makes it the quickest proof that the network, the hostname and TLS are all working:

   ```bash
   curl -s "https://<your-instance>/api/health/"
   ```

   A healthy instance replies with `"status": true`, alongside the state of the database and of the cache.
2. **Call a collection with your credential** and confirm the envelope comes back. `GET /api/v1/users/users/?limit=1` is a safe choice, and a 401 here with a healthy instance points at the credential, not the connection.
3. **Repeat the call from the machine that will run the integration.** An application's allowed source addresses are enforced, so a call that works from your workstation can still be refused from the server that needs it.

## Common errors

| Symptom                                                      | Cause                                                                                 | Fix                                                                        |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 401 with a signature that looks correct                      | The date header was formatted in the machine's own language, or the clock has drifted | Format the date in English, in GMT, and keep the host's clock synchronised |
| 401 only when the query string is present                    | The signature covered the path without its parameters                                 | Sign the request target exactly as sent                                    |
| An integration application authenticates as nobody           | `X-Source: datadike-pam` is missing                                                   | Add the header                                                             |
| A call succeeds but returns an empty collection              | The client is operating in the default organisation                                   | Send `X-PAM-ORG` with the intended organisation                            |
| A call works from your workstation and fails from the server | The application's allowed source addresses do not include that server                 | Add the address to the application                                         |
| 403 with a working credential                                | The user or application lacks permission for that resource                            | Check the role, or the application's account scope                         |
| `/api/docs` cannot be reached                                | The instance is addressed by a name the client cannot resolve, or TLS is failing      | Use the same address as **System settings › General › Site URL**           |

## Related pages

* [Application-to-application access](https://wiki.datadike.com/pam/administration/integrations/application-to-application.md) — retrieving a credential without a person
* [The credential vault](https://wiki.datadike.com/pam/administration/accounts/vault.md) — what those endpoints read from
* [Audit trail](https://wiki.datadike.com/pam/administration/audit/audit-trail.md) — where API calls are recorded
* [Configuration fields](https://wiki.datadike.com/pam/reference/configuration-fields.md) — the Site URL that clients should address
