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 or Create Organization Token API
A scoped, time-limited credential for a script or job	Scoped Organization token	Create Token API
A service calling Connector APIs on one integration	Integration token	Create Integration Token API
An AI agent using existing integrations	MCP token — integration usage scope	Create MCP Token API
An AI agent setting up new integrations	MCP token — management scope	Create MCP Token API
An AI agent with full account-owner access	MCP token — developer scope	Create MCP Token API

Attaching a token to every call

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

Authorization: Bearer <YOUR_TOKEN>

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

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

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 does the day-to-day work; the refresh token 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 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.

curl -i -X POST \
  https://api.synqly.com/v1/tokens \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": {
      "accounts": {
        "ids": [
          "account-123"
        ]
      }
    },
    "permission_set": "account-manager",
    "token_ttl": "20h"
  }'

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 for full parameters, or learn more about Organization 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:

curl -i -X POST \
  'https://api.synqly.com/v1/tokens/{accountId}/{integrationId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token_ttl": "10m"
  }'

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 for full parameters, or learn more about Integration 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:

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.

curl -i -X POST \
  https://api.synqly.com/v1/tokens/mcp \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token_ttl": "1h",
    "scope": {
      "integration_usage": {
        "account_id": "account-123",
        "restrict_to_connector_operations": [
          "siem_query_events"
        ]
      }
    }
  }'

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.

See the Create MCP Token API reference 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.