{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml","oas-api-reference/management.yml":"oas-api-reference/management.yml","oas-api-reference/connectors.yml":"oas-api-reference/connectors.yml"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample","tabs","tab"]},"type":"markdown"},"seo":{"title":"Create a Service Account","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-service-account","__idx":0},"children":["Create a Service Account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, you'll create a dedicated service identity in Synqly for an automated provisioning workflow. The service will be able to create accounts and issue integration tokens using narrowly scoped permissions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-scenario","__idx":1},"children":["The scenario"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Acme Corp is building ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Provisioning Service"]},", an internal automation that runs whenever a new customer signs up. It must:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a Synqly account for the customer and label it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Issue a short-lived Integration token once the customer selects a SIEM connector."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This service must operate independently from any human administrator credentials."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Synqly Organization token with administrator access, available from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.synqly.com"},"children":["Settings → API Keys"]}]},". This is used only for setup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A tool to make HTTP requests, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-identify-required-permissions","__idx":3},"children":["Step 1: Identify required permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provisioning Service needs two capabilities:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create and manage accounts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Issue integration tokens"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These map to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account-manager"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token-issuer"]}," permission sets."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While an administrator permission set could also work, it grants more access than this service requires. Narrow permissions reduce risk and make access easier to audit."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-create-two-roles","__idx":4},"children":["Step 2: Create two roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using your Organization token, create two roles scoped only to provisioning resources. Both roles are restricted to accounts labeled ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acme-provisioning"]}," in production."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"roles_create","language":"curl","parameters":{},"requestBody":{"name":"provisioning-service-accounts","resources":{"accounts":{"labels":["acme-provisioning"],"environments":["prod"],"ids":["52e9fc2e-e67f-4439-b85e-0c7e8070dfeb"]}},"permission_set":"account-manager"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"roles_create","language":"curl","parameters":{},"requestBody":{"name":"provisioning-service-token-issuer","resources":{"accounts":{"labels":["acme-provisioning"],"environments":["prod"],"ids":["52e9fc2e-e67f-4439-b85e-0c7e8070dfeb"]}},"permission_set":"token-issuer"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both roles use the same resource restrictions. This ensures the service can only operate on accounts it is explicitly allowed to manage."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-create-the-service-identity","__idx":5},"children":["Step 3: Create the service identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a service account (a Member) for Provisioning Service and bind both roles to it."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"members_create","language":"curl","parameters":{},"requestBody":{"name":"svc-provisioning@acme.io","secret":"<strong-secret>","role_binding":["provisioning-service-accounts","provisioning-service-token-issuer"],"type":"service"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This identity now has the combined permissions of both roles,  with the same resource restrictions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The effective access is the union of both roles, but always constrained by the shared boundary."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-choose-how-the-service-authenticates","__idx":6},"children":["Step 4: Choose how the service authenticates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provisioning Service needs its own runtime credential. There are two supported approaches:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Service account credential (persistent identity)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authenticate as the service account to obtain a TokenPair."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This creates a named, auditable identity tied to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["svc-provisioning@acme.io"]},". Access is revoked by disabling or deleting the member."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this approach when you want identity tracking and long-lived service ownership."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Scoped organization token (ephemeral credential)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, issue a short-lived ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/security-model/create-scoped-organization-tokens"},"children":["Scoped Organization 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":"24h"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This produces an ephemeral credential that expires automatically. It is useful for scheduled jobs or systems that prefer rotation over persistent identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When using this approach, you do not need to create a service identity (Steps 2 and 3)."]}," The Scoped Organization token is derived directly from your Organization token and carries its own resource restrictions — no Member or role bindings are required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account-manager"]}," permission set is sufficient here. This token is used only for account management operations; it does not issue integration tokens of its own, so the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token-issuer"]}," permission set is not needed."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both approaches result in the same effective permissions. The difference is lifecycle: one is identity-based, the other is time-bound."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-create-the-customer-account","__idx":7},"children":["Step 5: Create the customer account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using its provisioning credentials, the service creates a new account:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"accounts_create","language":"curl","parameters":{},"requestBody":{"name":"customer-acme-123","labels":["acme-provisioning"]},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label is critical. It ensures the account remains within the service's resource restriction and stays manageable by the same roles."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-issue-an-integration-token-for-the-customer","__idx":8},"children":["Step 6: Issue an integration token for the customer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the customer selects a SIEM integration, the service issues a short-lived Integration token."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/management.yml","operationId":"tokens_create_integration_token","language":"curl","parameters":{},"requestBody":{"token_ttl":"10m"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This token is used only by the customer's application to configure the integration. It is separate from the provisioning service's own credentials and is scoped only to the Connector APIs — it does not grant access to the Management APIs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer's application passes this token to the Connector API to perform provider operations:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api-reference/connectors.yml","operationId":"siem_query_events","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more detail on integration token scope and lifecycle, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/concepts/integration-access-tokens"},"children":["Integration Access Tokens"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-built","__idx":9},"children":["What you built"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You created a dedicated service identity with two narrowly scoped roles, both constrained by the same resource restriction. That identity operates only within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acme-provisioning"]}," production boundary."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The service can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create and manage accounts it owns"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Issue integration tokens for those accounts"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It cannot:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access other accounts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Escalate permissions beyond its roles"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This ensures that even if the service is compromised, the impact remains limited to a clearly defined boundary rather than the entire organization."]}]},"headings":[{"value":"Create a Service Account","id":"create-a-service-account","depth":1},{"value":"The scenario","id":"the-scenario","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Identify required permissions","id":"step-1-identify-required-permissions","depth":2},{"value":"Step 2: Create two roles","id":"step-2-create-two-roles","depth":2},{"value":"Step 3: Create the service identity","id":"step-3-create-the-service-identity","depth":2},{"value":"Step 4: Choose how the service authenticates","id":"step-4-choose-how-the-service-authenticates","depth":2},{"value":"Step 5: Create the customer account","id":"step-5-create-the-customer-account","depth":2},{"value":"Step 6: Issue an integration token for the customer","id":"step-6-issue-an-integration-token-for-the-customer","depth":2},{"value":"What you built","id":"what-you-built","depth":2}],"frontmatter":{"slug":"guides/security-model/build-a-service-account","seo":{"title":"Create a Service Account"}},"lastModified":"2026-07-02T06:20:08.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/security-model/build-a-service-account","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}