{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml","oas-api-reference/management.yml":"oas-api-reference/management.yml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Create a Scoped Token","siteUrl":"https://docs.synqly.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-scoped-token","__idx":0},"children":["Create a Scoped Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-pick-the-permission-set","__idx":2},"children":["Step 1: Pick the permission set"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose the permission set that matches what this credential needs to do — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account-manager"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["viewer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token-issuer"]},", and so on. If you're unsure what a given set allows, query the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.synqly.com/api-reference/management/permissionset"},"children":["Permission Sets API"]}," rather than guessing."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"One permission set per token"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission_set"]}," accepts a single value. Each scoped token carries exactly one permission set. If your job requires more than one (for example, both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account-manager"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["viewer"]},"), issue a separate token per permission set, or use a named ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/security-model/build-a-service-account"},"children":["service account"]}," with multiple role bindings instead."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-pick-the-resource-restriction","__idx":3},"children":["Step 2: Pick the resource restriction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Decide which objects the permission set should apply to:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"By account ID","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use when the credential should touch specific, already-known accounts:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"resources:\n  accounts:\n    ids: [\"account-123\", \"account-456\"]\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"By label + environment","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use when the credential should apply to a class of accounts rather than specific IDs:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"resources:\n  accounts:\n    labels: [\"acme-provisioning\"]\n    environments: [\"prod\"]\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both fields must match — AND logic, not OR. Valid environment values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"test\""]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"prod\""]},"."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"By integration category","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use when the credential's job is about a kind of connector rather than a specific account:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"resources:\n  integrations:\n    categories: [\"siem\", \"ticketing\"]\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-set-a-ttl","__idx":4},"children":["Step 3: Set a TTL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_ttl"]}," to how long this specific task actually needs to run. A nightly batch job might need ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"20h\""]},"; a one-shot migration script might need ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"30m\""]},". If the job runs again tomorrow, request a new token then."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-create-the-token","__idx":5},"children":["Step 4: Create the token"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"tokens_create_token","language":"curl","parameters":{},"requestBody":{"resources":{"accounts":{"labels":["acme-provisioning"],"environments":["prod"]}},"permission_set":"account-manager","token_ttl":"20h"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No role is created or persisted. The permission set and restriction exist only for the lifetime of this token."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-use-the-secret","__idx":6},"children":["Step 5: Use the secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token secret is returned once in the response (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-a-named-role-instead","__idx":7},"children":["When to use a named role instead"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you find yourself creating the same permission set + resource restriction combination more than a couple of times, define a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.synqly.com/api-reference/management/roles"},"children":["named role"]}," once and reuse it. Scoped tokens are for genuinely one-off access; repeated patterns are easier to audit as named roles."]}]},"headings":[{"value":"Create a Scoped Token","id":"create-a-scoped-token","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Pick the permission set","id":"step-1-pick-the-permission-set","depth":2},{"value":"Step 2: Pick the resource restriction","id":"step-2-pick-the-resource-restriction","depth":2},{"value":"Step 3: Set a TTL","id":"step-3-set-a-ttl","depth":2},{"value":"Step 4: Create the token","id":"step-4-create-the-token","depth":2},{"value":"Step 5: Use the secret","id":"step-5-use-the-secret","depth":2},{"value":"When to use a named role instead","id":"when-to-use-a-named-role-instead","depth":2}],"frontmatter":{"slug":"guides/security-model/create-scoped-organization-tokens","seo":{"title":"Create a Scoped Token"}},"lastModified":"2026-07-02T06:20:08.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/security-model/create-scoped-organization-tokens","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}