# 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](https://docs.synqly.com/api-reference/management/permissionset) 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](/guides/security-model/build-a-service-account) with multiple role bindings instead.

## Step 2: Pick the resource restriction

Decide which objects the permission set should apply to:

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


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

By label + environment
Use when the credential should apply to a class of accounts rather than specific IDs:


```yaml
resources:
  accounts:
    labels: ["acme-provisioning"]
    environments: ["prod"]
```

Both fields must match — AND logic, not OR. Valid environment values are `"test"` and `"prod"`.

By integration category
Use when the credential's job is about a kind of connector rather than a specific account:


```yaml
resources:
  integrations:
    categories: ["siem", "ticketing"]
```

## 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

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](https://docs.synqly.com/api-reference/management/roles) once and reuse it. Scoped tokens are for genuinely one-off access; repeated patterns are easier to audit as named roles.