> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt > Use this file to discover all available pages before exploring further. # Create service account > Create a service account using an admin session, personal access token, or service account token. Requires organization administration permission. Specify either organization scopes or an organization custom role UUID. For project access, use scopes ["system:member"] and projectAccess grants. The returned token is only available on creation; store it securely. ## OpenAPI ````yaml https://raw.githubusercontent.com/lightdash/lightdash/refs/heads/main/packages/backend/src/generated/swagger.json post /api/v1/service-accounts openapi: 3.0.0 info: title: Lightdash API version: 3.25.0 description: > Open API documentation for all public Lightdash API endpoints. # Authentication Authenticate using the Authorization header with either 'ApiKey ' or 'Bearer '. Create a Personal Access Token by following this guide: https://docs.lightdash.com/references/personal_tokens Self-hosted provisioning can use the admin token configured with LD_SETUP_SERVICE_ACCOUNT_TOKEN to create scoped service accounts through the Service Accounts API. license: name: MIT contact: name: Lightdash Support email: support@lightdash.com url: https://docs.lightdash.com/help-and-contact/contact/contact_info/ servers: - url: / security: [] tags: - name: My Account description: These routes allow users to manage their own user account. - name: Organizations description: >- Each user is a member of a single organization. These routes allow users to manage their organization. Most actions are only available to admin users. - name: Projects description: >- Projects belong to a single organization. These routes allow users to manage their projects, browse content, and execute queries. Users inside an organization might have access to a project from an organization-level role or they might be granted access to a project directly. - name: Spaces description: >- Spaces allow you to organize charts and dashboards within a project. They also allow granular access to content by allowing you to create private spaces, which are only accessible to the creator and admins. - name: Roles & Permissions description: >- These routes allow users to manage roles and permissions for their organization. externalDocs: url: https://docs.lightdash.com/references/roles - name: Service Accounts description: >- Create and manage machine credentials for your organization. Requires organization administration permission. Use predefined organization scopes, a custom organization role, or grants to selected projects. Credentials cannot grant more access than the caller holds. - name: Query description: >- These routes allow users to execute and manage queries against their data warehouse. This includes metric queries, SQL queries, and retrieving query results. paths: /api/v1/service-accounts: post: tags: - Service Accounts summary: Create service account description: >- Create a service account using an admin session, personal access token, or service account token. Requires organization administration permission. Specify either organization scopes or an organization custom role UUID. For project access, use scopes ["system:member"] and projectAccess grants. The returned token is only available on creation; store it securely. operationId: CreateServiceAccount parameters: [] requestBody: description: service account details required: true content: application/json: schema: $ref: '#/components/schemas/ApiCreateServiceAccountRequest' description: service account details responses: '201': description: Created content: application/json: schema: properties: results: $ref: '#/components/schemas/ServiceAccountWithToken' status: type: string enum: - ok nullable: false required: - results - status type: object default: description: Error content: application/json: schema: $ref: '#/components/schemas/ApiErrorPayload' security: [] components: schemas: ApiCreateServiceAccountRequest: allOf: - $ref: '#/components/schemas/Pick_ServiceAccount.expiresAt-or-description_' - properties: projectAccess: items: $ref: '#/components/schemas/ServiceAccountProjectAccessInput' type: array description: Project grants. Requires scopes = ["system:member"]. roleUuid: type: string nullable: true description: Custom organization role UUID, instead of scopes. scopes: items: $ref: '#/components/schemas/ServiceAccountScope' type: array description: >- Organization role scopes. Provide either scopes or roleUuid, not both. type: object ServiceAccountWithToken: allOf: - $ref: '#/components/schemas/ServiceAccount' - properties: token: type: string description: >- Bearer token returned only when creating or rotating the service account. required: - token type: object ApiErrorPayload: properties: error: properties: data: $ref: '#/components/schemas/AnyType' description: Optional data containing details of the error message: type: string description: A friendly message summarising the error name: type: string description: Unique name for the type of error statusCode: type: number format: integer description: HTTP status code required: - name - statusCode type: object status: type: string enum: - error nullable: false required: - error - status type: object description: |- The Error object is returned from the api any time there is an error. The message contains Pick_ServiceAccount.expiresAt-or-description_: properties: description: type: string expiresAt: type: string format: date-time nullable: true description: Expiration timestamp, or null for a token that does not expire. required: - description - expiresAt type: object description: From T, pick a set of properties whose keys are in the union K ServiceAccountProjectAccessInput: properties: roleUuid: type: string description: Custom project role belonging to this organization. role: $ref: '#/components/schemas/ProjectMemberRole' description: Predefined project role. Provide exactly one of role or roleUuid. projectUuid: type: string required: - projectUuid type: object description: >- Project-scoped grant for a Member-shape SA. When `projectAccess` is non-empty on a create request, `scopes` must be `['system:member']` — any other scope combination is rejected at the service layer so the SA's effective access is unambiguously project-only. Each grant must carry exactly one of `role` (system) or `roleUuid` (custom). The XOR is enforced at the service layer (compile-time `never` discriminator unions are not used here — see note on `ServiceAccountProjectGrant`). Mixed grants across the same `projectAccess` array are allowed — e.g. one project on stock Viewer and another on a custom role. ServiceAccountScope: enum: - scim:manage - org:admin - org:edit - org:read - system:member - system:admin - system:developer - system:editor - system:interactive_viewer - system:viewer type: string ServiceAccount: properties: roleUuid: type: string nullable: true userUuid: type: string scopes: items: $ref: '#/components/schemas/ServiceAccountScope' type: array rotatedAt: type: string format: date-time nullable: true lastUsedAt: type: string format: date-time nullable: true description: type: string expiresAt: type: string format: date-time nullable: true description: Expiration timestamp, or null for a token that does not expire. createdAt: type: string format: date-time organizationUuid: type: string createdBy: properties: lastName: type: string firstName: type: string userUuid: type: string required: - lastName - firstName - userUuid type: object nullable: true createdByUserUuid: type: string nullable: true uuid: type: string required: - roleUuid - userUuid - scopes - rotatedAt - lastUsedAt - description - expiresAt - createdAt - organizationUuid - createdBy - createdByUserUuid - uuid type: object AnyType: description: |- This AnyType is an alias for any The goal is to make it easier to identify any type in the codebase without having to eslint-disable all the time These are only used on legacy `any` types, don't use it for new types. This is added on a separate file to avoid circular dependencies. ProjectMemberRole: enum: - viewer - interactive_viewer - editor - developer - admin type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.