Practical recommendations for securely issuing and managing tokens, roles, and service identities in Synqly. These complement the Security Model Overview and help reduce risk in day-to-day usage.
Protect the Organization token
Store securely. Never use in runtime services or client-side code.
Use least-privilege permissions
Start with the most restrictive set that satisfies the use case.
Match token lifetime to workload
Short tasks get short TTLs. Reduces exposure if a credential leaks.
Pin MCP tokens to an account
Always set AccountId explicitly in production.
Restrict MCP tool visibility
Limit tools to only what the agent actually needs.
Compose roles, don't bloat them
Bind multiple narrow roles rather than one broad role.
Audit role bindings regularly
Bindings don't expire. Review and remove what's no longer needed.
Rotate on exposure
Secrets are shown once. If lost or leaked, rotate immediately.
The Organization token (available in Settings → API Keys) carries broad administrative authority. It should only be used for initial setup and controlled administrative operations — not for routine runtime workloads.
- Do not use it in client-side applications
- Do not commit it to source control
- Do not embed it in configuration files used by runtime services
Store it in a secure secrets manager and use it only to create roles, service accounts, and scoped credentials.
Always start with the most restrictive permission set that satisfies the use case. If additional access is required, expand scope incrementally rather than starting broad and cutting back.
Where multiple capabilities are needed, bind multiple narrow roles to the same member rather than creating a single broad role. This keeps each role auditable and reusable independently.
Set token_ttl based on how long the workload actually needs access — not longer.
| Workload type | Recommended TTL |
|---|---|
| One-shot migration or script | "30m" or less |
| Nightly batch job | "20h" or less |
| Long-running service | Use a member identity instead |
Short-lived credentials reduce exposure if leaked and limit the window of misuse. If the job runs again tomorrow, request a new token then.
When issuing MCP tokens for production, always set account_id explicitly rather than relying on environment-level scoping alone.
Explicit account scoping ensures the agent operates within a single account boundary, regardless of environment. Omitting it allows the token to reach any account in that environment.
When using MCP tokens with integration-usage scope, set restrict_to_connector_operations to limit which tools the MCP server advertises to the agent.
An agent can only invoke tools that are visible to it. Fewer visible tools means a smaller blast radius if the agent is misdirected or compromised.
If a service requires multiple capabilities, build from narrow pieces:
Do this
Create one role per capability. Bind all required roles to the same service account.
Each role stays narrow, reusable, and independently auditable.
Avoid this
Creating a single role that combines all required permissions into one broad grant.
Broad roles are harder to audit and tend to accumulate excess access over time.
A member's effective access is the union of all its role bindings — and those bindings do not expire automatically.
Review role assignments periodically and remove bindings that are no longer required. This ensures access stays aligned with current operational needs.
See Manage Members and Role Bindings for how to update and remove bindings.
Synqly secrets are shown only once at creation time. If a credential is lost or suspected to be exposed:
- Create a new credential
- Update all dependent systems to use it
- Revoke or delete the old one
Treat rotation as a normal operational procedure, not an emergency response.
A token can never create credentials with greater privileges than itself.
When issuing tokens, ensure the issuing credential is scoped to the minimum required access. Any token created from it will inherit and respect that boundary, even if the issuing service is later compromised.