# API Tokens and Access Control

All Synqly API calls are authenticated using bearer tokens. Choose the appropriate token type for your use case and include it with every request.

## What are you building?

| You're building… | Token type | Created via |
|  --- | --- | --- |
| A backend managing accounts, members, roles | Organization token | [Synqly UI](https://app.synqly.com) or [Create Organization Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_token) |
| A scoped, time-limited credential for a script or job | Scoped Organization token | [Create Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_token) |
| A service calling Connector APIs on one integration | Integration token | [Create Integration Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_integration_token) |
| An AI agent using existing integrations | MCP token — integration usage scope | [Create MCP Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_mcp_token) |
| An AI agent setting up new integrations | MCP token — management scope | [Create MCP Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_mcp_token) |
| An AI agent with full account-owner access | MCP token — developer scope | [Create MCP Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_mcp_token) |


## Attaching a token to every call

Every token goes in the same place — the `Authorization` header:


```
Authorization: Bearer <YOUR_TOKEN>
```

Using an SDK
If you initialize a Synqly SDK client with a token, the SDK attaches it to every call automatically:


```go
client := mgmtClient.NewClient(
    mgmtClient.WithAuthToken(synqlyOrgToken),
)
```

Direct HTTP

```bash
curl --request GET \
     --url https://api.synqly.com/v1/accounts \
     --header "Authorization: Bearer $SYNQLY_ORG_TOKEN"
```

Every token is a **TokenPair** under the hood — an access token you use on API calls, and a refresh token used only to rotate it. This mirrors the OAuth 2.0 model: the [access token](https://www.rfc-editor.org/info/rfc6749/#section-1.4) does the day-to-day work; the [refresh token](https://www.rfc-editor.org/info/rfc6749/#section-1.5) lives in a vault until rotation time.

## Organization tokens

Use an Organization token to call the **Management API** — creating accounts, configuring integrations, managing members and roles, issuing other tokens.

Get your initial Organization token from the [Synqly UI](https://app.synqly.com) under **Settings → API Keys**. This token carries broad organizational authority; store it securely and never expose it in client-side code.

### Scoped Organization tokens

For one-off access — a script, an automated job, a short-lived credential scoped to a single account — you can define the permission set and resource restrictions **inline at token creation time**. No role definition is created or stored; the restrictions exist only for the lifetime of the token.

That's an Organization token valid for 20 hours, with `account-manager` permissions, scoped to `account-123` only.

Scoped token vs. named role: when to use which
Use a **named role** when the same permission set + resource combination will be assigned to multiple members or tokens over time — define it once, reuse it everywhere.

Use a **scoped token** when the access is one-off or automation-specific and there is no reason to persist the role definition.

The authorization behavior at runtime is identical either way.

See the [Create Token API reference](https://docs.synqly.com/api-reference/management/tokens/tokens_create_token) for full parameters, or [learn more about Organization tokens](/guides/concepts/organization-access-tokens).

## Integration tokens

Use an Integration token to call **Connector APIs** — pulling events from a SIEM, pushing a ticket, writing to storage. This token is scoped to a single account and integration; it cannot touch the Management API.

Issue one per integration, per session. Short TTLs are the norm:

Two separate clients, two separate APIs
Your Organization token works with the Management API client. Your Integration token works with the Connector API client. These tokens are not interchangeable — using the wrong token for the wrong API will be rejected.

See the [Create Integration Token API reference](https://docs.synqly.com/api-reference/management/tokens/tokens_create_integration_token) for full parameters, or [learn more about Integration tokens](/guides/concepts/integration-access-tokens).

## MCP tokens

MCP tokens are short-lived credentials for AI agents. Every MCP token has a configurable lifetime via `token_ttl` — default is **1 hour**, maximum is **24 hours** — specified as a duration string: `"1h"`, `"30m"`, `"1s"`.

There are two scope types, each matching a distinct agent role:

Integration usage
**The agent uses existing integrations.** Issue this scope when an agent should query or act on already-configured integrations — but should not be able to create or modify them.

This token carries the `mcp-integrations-use-only` permission set, scoped to `account-123`.

`RestrictToConnectorOperations` controls which tools the MCP server advertises to the agent. If you specify operations, the agent can only see — and call — those tools. **If you omit it, the MCP server advertises all available tools for that account.** Specify it to give the agent the minimum footprint it needs.

Management
**The agent sets up integrations.** Issue this scope when an agent needs to create or configure integrations — onboarding flows, setup wizards — but should not be able to call Connector APIs through them.

This token carries `mcp-management` permissions. Two optional fields narrow the scope:

- `AccountId` — restricts the token to a specific account. Recommended for production. When set, it takes precedence and the `Environment` field is ignored.
- `Environment` — restricts to a specific environment (`"test"` or `"prod"`). Useful for blanket sandbox access when you don't need account-level precision.


Prefer AccountId in production
`AccountId` pins the token to a single account regardless of environment. For production agents, always specify `AccountId` rather than relying on `Environment` alone.

See the [Create MCP Token API reference](https://docs.synqly.com/api-reference/management/tokens/tokens_create_mcp_token) for the full MCP token API surface.

## Token delegation follows least privilege

Synqly allows tokens to delegate access, but delegated access can never exceed the permissions or resource scope of the issuing token. This ensures that authority can be distributed without expanding the original access boundaries.

| A token with… | Cannot issue a token with… |
|  --- | --- |
| Access limited to `account-123` | Access to `account-456` |
| The `viewer` permission set | The `administrator` permission set |
| A resource restriction | Broader access outside that restriction |


Permission ceilings are enforced
Every token has a maximum permission and resource scope. Tokens created from it inherit that ceiling and can only reduce it.

Because these limits are enforced by the platform, a downstream service cannot grant broader access than it was originally given, even if that service is later compromised.