Create a Scoped Token

Use this when you need a short-lived credential for a script or job and don't want to define a named role for something you'll only use once or twice.

Before you start

You need an existing Organization token with enough authority to issue the access you're about to scope down. Delegation only shrinks — whatever you grant here must already be within what your issuing token holds.

Step 1: Pick the permission set

Choose the permission set that matches what this credential needs to do — account-manager, viewer, token-issuer, and so on. If you're unsure what a given set allows, query the Permission Sets API rather than guessing.

One permission set per token

permission_set accepts a single value. Each scoped token carries exactly one permission set. If your job requires more than one (for example, both account-manager and viewer), issue a separate token per permission set, or use a named service account with multiple role bindings instead.

Step 2: Pick the resource restriction

Decide which objects the permission set should apply to:

Use when the credential should touch specific, already-known accounts:

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

Step 3: Set a TTL

Set token_ttl to how long this specific task actually needs to run. A nightly batch job might need "20h"; a one-shot migration script might need "30m". If the job runs again tomorrow, request a new token then.

Step 4: Create 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": {
        "labels": [
          "acme-provisioning"
        ],
        "environments": [
          "prod"
        ]
      }
    },
    "permission_set": "account-manager",
    "token_ttl": "20h"
  }'

No role is created or persisted. The permission set and restriction exist only for the lifetime of this token.

Step 5: Use the secret

The token secret is returned once in the response (token.Result.Secret). Pass it directly to the process that needs it — a secrets manager or an environment variable for the job. When the TTL elapses, the token stops working with nothing to clean up.

When to use a named role instead

If you find yourself creating the same permission set + resource restriction combination more than a couple of times, define a named role once and reuse it. Scoped tokens are for genuinely one-off access; repeated patterns are easier to audit as named roles.