> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloud.cdata.com/llms.txt > Use this file to discover all available pages before exploring further. # サービスアカウントにワークスペースロールを割り当て > Assign a workspace-scoped role (system or custom access) to a service account. This is how `workspace_admin` and other workspace-scoped system roles are granted; only the account-wide `admin` role is assigned via `POST /service-accounts/{id}/roles`. The service account must be a direct member of the target workspace before this call. ## OpenAPI ````yaml ja/API/Management-API.yaml POST /service-accounts/{id}/workspaces/{workspace_id}/roles openapi: 3.1.0 info: title: CData Connect AI Management API version: v1 description: > The Connect AI Management API provides programmatic control over enterprise platform administration. Base path: /api/v1/admin. Use it to manage users, service accounts, roles, and resource permissions without manual UI operations. The API follows OAS 3.0 standards with OAuth 2.0 scoped authentication. Authentication: use OAuth 2.0 client credentials, or send a personal access token (PAT) with HTTP Basic authentication by using the header `Authorization: Basic base64(email:PAT)`. On versioning: the version prefix is incremented when breaking changes require it. A new /api/v2/admin path will be introduced with a 6-month deprecation notice before any v1 endpoint is retired. On human users vs. service accounts: human users are provisioned and lifecycle-managed by SCIM; the Management API handles direct overrides and atomic deprovisioning. Service accounts (CI/CD pipelines, IaC tooling, Terraform) are fully managed via the Management API and are not SCIM-owned. servers: - url: https://cloud.cdata.com/api/v1/admin description: Production base URL security: - oauth2: [] - basicAuth: [] tags: - name: Users description: > Lifecycle management for human users: create, update, deprovision, and manage direct role assignments, workspace-scoped roles, and direct resource permissions. SCIM handles group-based provisioning and user creation at scale; this API handles direct overrides and atomic deprovisioning. - name: Service Accounts description: > Full lifecycle management for machine identities (CI/CD pipelines, IaC tooling, Terraform automation). Service accounts are not SCIM-owned and authenticate via OAuth 2.0 client credentials using the `client_id` returned on creation. - name: Projects description: > List the projects in a workspace. Use a project's `project_id` when you create or list virtual keys for that project. - name: Virtual Keys description: > Create, list, disable, re-enable, and revoke LLM Gateway virtual keys. A virtual key is the credential a client sends to the LLM Gateway to authenticate, and it is issued to a user or service account for a project. The full key secret is returned only once, in the create response. Revoking a key is permanent, and the record is kept for auditing. Callers must be an Admin, or a Workspace Admin of the workspace in the path. The account must have the AI Gateway and LLM Gateway enabled; revoking a key requires only the AI Gateway. Each account is limited to 600 Management API calls per minute, and revoking or disabling a key never counts against the limit. - name: Roles description: > Role definitions: the permission vocabulary that users, service accounts, and groups reference. Two types exist: `system_role` (built-in, non-modifiable) and `access_role` (custom, fully manageable). Access roles are defined once for the account and assigned per workspace. System roles other than `admin` are workspace-scoped, and `admin` is account-wide. - name: Groups description: > Read SCIM-synced and API-managed groups, and assign workspace-scoped roles to groups so that group membership confers the correct Connect AI access. Membership of SCIM groups is owned by the identity provider (IdP). - name: Workspaces description: > Create and manage workspaces, which are isolation boundaries at the account level, and manage workspace membership for users, service accounts, and groups. paths: /service-accounts/{id}/workspaces/{workspace_id}/roles: post: tags: - Service Accounts summary: Assign Service Account Workspace Role description: > Assign a workspace-scoped role (system or custom access) to a service account. This is how `workspace_admin` and other workspace-scoped system roles are granted; only the account-wide `admin` role is assigned via `POST /service-accounts/{id}/roles`. The service account must be a direct member of the target workspace before this call. operationId: assignServiceAccountWorkspaceRole parameters: - name: id in: path required: true description: Service account identifier (UUID). schema: type: string format: uuid - name: workspace_id in: path required: true description: Workspace identifier (UUID). schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignRoleRequest' example: role_id: 00000000-0000-0000-0000-000000000020 responses: '201': description: Created. Returns the new workspace role assignment. content: application/json: schema: $ref: '#/components/schemas/ServiceAccountWorkspaceRoleAssignment' example: id: r3b4c5d6-e7f8-9012-abcd-ef1234567890 service_account_id: c3d4e5f6-a7b8-9012-cdef-123456789012 workspace_id: w1b2c3d4-e5f6-7890-abcd-ef1234567890 role_id: 00000000-0000-0000-0000-000000000020 role_name: workspace_admin role_type: system_role granted_at: '2026-06-01T12:00:00Z' granted_by: 00000000-0000-0000-0000-000000000001 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Service account not found value: error: code: SERVICE_ACCOUNT_NOT_FOUND message: The specified service account does not exist. workspace_not_found: summary: Workspace not found value: error: code: WORKSPACE_NOT_FOUND message: The specified workspace does not exist. '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: system_role_limit: summary: Service account already holds a workspace system role value: error: code: SYSTEM_ROLE_LIMIT message: >- The service account already holds a workspace-scoped system role in this workspace. One per workspace. '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: role_not_found: summary: Role does not exist value: error: code: ROLE_NOT_FOUND message: The specified role does not exist. entity_not_in_workspace: summary: Service account not a workspace member value: error: code: ENTITY_NOT_IN_WORKSPACE message: >- The service account must be a direct member of the target workspace before a workspace-scoped role can be assigned. security: - oauth2: - management:service-accounts:write - basicAuth: [] components: schemas: AssignRoleRequest: type: object required: - role_id properties: role_id: type: string format: uuid description: Role to assign. Must exist in the organization. ServiceAccountWorkspaceRoleAssignment: type: object description: A workspace-scoped role assignment for a service account. properties: id: type: string format: uuid description: Assignment identifier. service_account_id: type: string format: uuid description: The service account this workspace role is assigned to. workspace_id: type: string format: uuid description: The workspace this role is assigned to. role_id: type: string format: uuid description: The role identifier. role_name: type: string description: The name of the role. role_type: type: string enum: - system_role - access_role description: The type of the role. granted_at: type: string format: date-time description: ISO 8601 UTC. granted_by: type: string format: uuid description: The user who granted the workspace role. ErrorResponse: type: object properties: error: type: object description: Error details. properties: code: type: string description: SCREAMING_SNAKE_CASE error code. message: type: string description: Human-readable error description. details: type: array description: Additional error context, present only where needed. items: type: object additionalProperties: true securitySchemes: oauth2: type: oauth2 description: > OAuth 2.0 client credentials. Alternatively, you can authenticate with a personal access token (PAT) by sending `Authorization: Basic base64(email:PAT)`. flows: clientCredentials: tokenUrl: https://cloud-login.cdata.com/oauth/token scopes: management:users:read: Read access to user resources. management:users:write: Write access to user resources. management:service-accounts:read: Read access to service account resources. management:service-accounts:write: Write access to service account resources. management:roles:read: Read access to role resources. management:roles:write: Write access to role resources. management:groups:read: Read access to group resources. management:groups:write: Write access to group resources. management:workspaces:read: Read access to workspace resources. management:workspaces:write: Write access to workspace resources. basicAuth: type: http scheme: basic description: > HTTP Basic authentication with a personal access token (PAT). Send `Authorization: Basic base64(email:PAT)`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.