Synqly Authorization Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This guide explains how to control user and token authorization in the Synqly platform.

Overview

Synqly uses a flexible RBAC (Role-Based Access Control) system with support for:

• Fine-grained permission sets
• Granting access to specific accounts and/or integrations
• Creation of roles for specific use cases
• Adhoc tokens with inline restrictions
• Integration-specific tokens
• MCP (Model Context Protocol) tokens

The authorization system is built on three core concepts:

1. Permission Sets - Define what API actions can be performed
2. Resources - Define which accounts/integrations/organizations can be accessed
3. Roles - Combine permission sets with resource restrictions

Authorization can be applied through:

• Members with role bindings for human users or service accounts
• Adhoc Tokens with inline resource/permission restrictions (for programmatic access)

Permission Sets

Permission sets define the API actions a token can perform. Available permission sets:

Permission Set Details

Each permission set grants specific actions on specific API resources. You may restrict the resources that a token can access by using the resources field when creating a token or when creating a role.

See the Permission Sets API reference to list permission sets or get the details of a specific permission set. This API gives you the details of the API actions that are granted by each permission set.

Resource Restrictions

Resources control which objects a token or role can access. Synqly supports restricting access to accounts or integrations and uses an attribute-based approach to specifying these restrictions.

1. Account Restrictions

You can restrict access to accounts by specifying the account IDs, labels, or environments.

For example, to restrict access to the account with the ID account-123 or account-456, you would use the following:

resources:
  accounts:
    ids: ["account-123", "account-456"]

Note that you can also use the wildcard character * to grant access to all accounts. You may specify accounts by ID or by name.

Alternatively, you can restrict access to accounts by specifying the labels or environments.

resources:
  accounts:
    labels: ["customer-success-team"]
    environments: ["test", "prod"]

Important: When both labels and environments are specified, BOTH must match (AND logic).

2. Integration Restrictions

You can restrict access to integrations by specifying the categories.

resources:
  integrations:
    categories: ["siem", "storage", "ticketing"]  # Restrict to specific connector categories

This is used, for example, when you want to create a management token that can only generate tokens for specific connector categories.

Roles

Roles are named combinations of permission sets and resource restrictions. They can be:

• Created via the Roles API
• Bound to members via role_binding

Creating a Role

You can create a role with resource restrictions by using the Roles API.

role, err := client.Roles.Create(ctx, &mgmt.CreateRoleRequest{
    Name: mgmt.String("production-account-manager"),
    Resources: &mgmt.Resources{
        Accounts: &mgmt.RoleAccounts{
            Environments: []mgmt.Environment{"prod"},
            Labels:       []string{"customer-success-team"},
        },
    },
    PermissionSet: mgmt.PermissionsAccountManager,
})

The above shows an example using the Synqly Go SDK; however, the other SDKs have similar APIs.

Binding Roles to Members

You can bind roles to members by using the Members API.

member, err := client.Members.Create(ctx, &mgmt.CreateMemberRequest{
    Name:        "user@example.com",
    Secret:      "password123",
    RoleBinding: []mgmt.RoleName{"production-account-manager"},
})

When a member has multiple role bindings, access is granted if ANY role permits the action (OR logic).

The example above will create the user user@example.com the permission set account-manager on all accounts with the label customer-success-team and the environment prod.

As another example, you may want to restrict developers to the test environment only. You can do this by creating a role with the following:

role, err := client.Roles.Create(ctx, &mgmt.CreateRoleRequest{
    Name: mgmt.String("developers"),
    Resources: &mgmt.Resources{
        Accounts: &mgmt.RoleAccounts{
            Environments: []mgmt.Environment{"test"},
        },
    },
    PermissionSet: mgmt.PermissionsAdministrator,
})

Using the above, any user with the role developers will have admin access to all accounts in the test environment.

Adhoc Tokens

Adhoc tokens allow creating tokens with inline resource and permission restrictions without creating named roles.

They can be created using the Tokens API. For example:

token, err := client.Tokens.CreateToken(ctx, &mgmt.CreateTokenRequest{
    Resources: &mgmt.Resources{
        Accounts: &mgmt.RoleAccounts{
            Ids: []string{"account-123"},
        },
    },
    PermissionSet: mgmt.PermissionsAccountManager,
    TokenTtl:      "24h",
})

The example above will create a token valid for 24 hours with the permission set account-manager on the account with the ID account-123.

Token Scoping Rules

Critical: Tokens can only be reduced in scope, never expanded.

• A token cannot grant access to accounts it doesn't have access to
• A token cannot grant permissions it doesn't have
• A token cannot remove resource restrictions if the parent token has them

Integration Tokens

Accessing an integration is done through a token that is scoped to the integration. This token is used to authenticate requests to the Engine API. Such tokens are generally created as session tokens and only used for the a short period of time.

Using the Go SDK, you can create an integration token with the following:

integrationToken, err := client.Tokens.CreateIntegrationToken(ctx,
    accountId,
    integrationId,
    &mgmt.CreateIntegrationTokenRequest{
        TokenTtl: "10m",
    },
)

// Use with Engine API
client := engineClient.NewClient(
    engineClientOption.WithToken(integrationToken.Result.Secret),
)

Note: Integration tokens can only access the Engine API. Management tokens cannot access the Engine API, and integration tokens cannot access the Management API.

For full details on creating integration tokens, see the Integration Tokens API reference.

MCP Tokens

MCP tokens are specialized tokens for Model Context Protocol servers.

MCP Integration Usage Scope

For agents that need to use existing integrations:

mcpToken, err := client.Tokens.CreateMCPToken(ctx, &mgmt.CreateMCPTokenRequest{
    TokenTtl: "1h",
    Scope: &mgmt.MCPTokenScope{
        IntegrationUsage: &mgmt.MCPIntegrationUsageScopeOptions{
            AccountId: "account-123",
            RestrictToConnectorOperations: []mgmt.OperationId{"siem_query_events"},
        },
    },
})

Of note, the MCP token created by the above API will have the permission set mcp-integrations-use-only on the account with the ID account-123. Additionally, when used, the MCP server will only advertise the required tools and the siem_query_events tool. No other tools will be advertised. You can use this to restrict the tools that are advertised to an agent.

MCP Management Scope

For agents that need to create/manage integrations:

mcpToken, err := client.Tokens.CreateMCPToken(ctx, &mgmt.CreateMCPTokenRequest{
    TokenTtl: "1h",
    Scope: &mgmt.MCPTokenScope{
        Management: &mgmt.MCPManagementScopeOptions{
            Environment: mgmt.EnvironmentTest.Ptr(),
            AccountId:   "account-123",  // Optional, overrides environment
        },
    },
})