> For the complete documentation index, see [llms.txt](https://synthesys-2.gitbook.io/synthesys-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/authentication.md).

# Authentication

Access to the Synthesys Network API is granted at the environment level — your organization is provisioned a hostname and the network controls that govern who can reach it. There are no per-request bearer tokens, API keys, or signing schemes layered on top of the documented endpoints. Treat the API as you would treat any internal service that is reachable only from your own infrastructure: keep its hostname out of public configuration, route requests through your backend rather than the browser, and lock down outbound network access from anywhere that should not be calling it.

What the API **does** care about is **attribution** — knowing which actor in your system caused a given write. That's done with a single optional request header.

### The `x-actor` header

Every write endpoint accepts an optional **`x-actor`** request header. The value is recorded into the affected record's `createdBy` (on first write) and `updatedBy` (on every write) audit fields. If `x-actor` is omitted, both default to the literal string `"system"`.

bash

```bash
curl -sX POST $BASE/admin/entity \
  -H 'Content-Type: application/json' \
  -H 'x-actor: alice@example.com' \
  -d '{"type":"IS","data":{"name":"Franklin Templeton","jurisdiction":"US"}}'
```

You can put anything human-meaningful into `x-actor`. Typical values are an email, a service identifier, or a short tag like `bo-import` for back-office imports. The API does not validate the format, but for forward compatibility we recommend using a stable identifier rather than a free-form description, and reusing the same value across calls from the same actor.

`x-actor` is **safe to send on read endpoints too** — it is simply ignored there. This means you can centralise the header in your HTTP layer and not branch on method.

#### Setting `x-actor` from common HTTP clients

**Node.js (`fetch`):**

javascript

```javascript
await fetch(`${BASE}/admin/entity`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-actor': process.env.ACTOR ?? 'system',
  },
  body: JSON.stringify({ type: 'IS', data: { name: 'Franklin Templeton', jurisdiction: 'US' } }),
});
```

**Python (`requests`):**

python

```python
import os, requests
requests.post(
    f"{BASE}/admin/entity",
    headers={"x-actor": os.getenv("ACTOR", "system")},
    json={"type": "IS", "data": {"name": "Franklin Templeton", "jurisdiction": "US"}},
)
```

### Recommended integration posture

Build your integration so that the network boundary is the only thing standing between an attacker and the API, and so that audit attribution is correct from day one:

* **Pull the base URL from environment variables.** Never hardcode the hostname into source-controlled code; it should differ per environment (development, staging, production) and rotate without a code change.
* **Centralise outbound HTTP through a single helper.** Setting `x-actor`, applying timeouts, and unwrapping the response envelope all belong in one function. Every call site should use that helper rather than constructing requests inline.
* **Always send `x-actor`.** Audit fields are useless if every record is attributed to `"system"`. Choose a stable identifier per actor and pass it through.
* **Treat `4xx` responses as terminal errors and `5xx` as transient.** Retry the latter with exponential backoff; surface the former to the operator who issued the call.
* **Don't send credentials in URL parameters.** No part of the API requires this, and putting anything sensitive in a query string risks leaking it to logs and proxies.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.