> ## 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. # ロールの作成 > Create a custom access role in the account. System roles cannot be created through the API. Access roles are defined once for the account and can be assigned in any workspace. The permissions of a role take effect only in the workspace of each referenced connection. ## OpenAPI ````yaml ja/API/Management-API.yaml POST /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: /roles: post: tags: - Roles summary: Create Role description: >- Create a custom access role in the account. System roles cannot be created through the API. Access roles are defined once for the account and can be assigned in any workspace. The permissions of a role take effect only in the workspace of each referenced connection. operationId: createRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRoleRequest' example: name: Sales Read Only description: Read access to the Salesforce connection. permissions: - connection_id: c3d4e5f6-a7b8-4901-8cde-f23456789012 operations: - read type: connection responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Role' example: id: 9c8b7a65-4d3e-4f21-b0a9-8c7d6e5f4a30 name: Sales Read Only type: access_role description: Read access to the Salesforce connection. permissions: - connection_id: c3d4e5f6-a7b8-4901-8cde-f23456789012 operations: - read type: connection created_at: '2026-06-01T12:00:00Z' created_by: 00000000-0000-0000-0000-000000000001 '400': $ref: '#/components/responses/ValidationError' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: role_name_conflict: summary: Role name already used value: error: code: ROLE_NAME_CONFLICT message: A role with this name already exists in this account. '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_operation: summary: Invalid operation value value: error: code: INVALID_OPERATION message: One or more operation values are not valid. invalid_type: summary: Invalid permission type value: error: code: INVALID_PERMISSION_TYPE message: >- One or more type values are not valid. Must be connection. connection_not_found: summary: Connection not found value: error: code: CONNECTION_NOT_FOUND message: >- One or more connection_id values do not reference a connection in this account. security: - oauth2: - management:roles:write - basicAuth: [] components: schemas: CreateRoleRequest: type: object required: - name - permissions properties: name: type: string description: Unique display name within the account. description: type: string description: What this role permits. permissions: type: array items: type: object required: - connection_id - operations - type properties: connection_id: type: string format: uuid description: >- The connection this permission governs. It can reference a connection in any workspace of the account. The permission takes effect only where the role is assigned in that connection's workspace. operations: type: array items: type: string enum: - create - read - update - delete - execute description: One or more operations to permit on the connection. type: type: string enum: - connection description: >- Always `connection`. Classifies what category of resource the permission governs. description: Connection-level permission grants. Role: type: object properties: id: type: string format: uuid description: Role identifier. name: type: string description: Role display name. type: type: string enum: - system_role - access_role description: >- `system_role`: built-in, non-modifiable. `access_role`: custom, fully manageable. description: type: string nullable: true description: What the role permits. permissions: type: array items: type: object required: - connection_id - operations - type properties: connection_id: type: string format: uuid description: >- The connection this permission governs. It can reference a connection in any workspace of the account. The permission takes effect only where the role is assigned in that connection's workspace. operations: type: array items: type: string enum: - create - read - update - delete - execute description: One or more operations to permit on the connection. type: type: string enum: - connection description: >- Always `connection`. Classifies what category of resource the permission governs. description: >- Connection permissions. Returned only for `access_role` roles on single-role responses. created_at: type: string format: date-time description: ISO 8601 UTC. `null` for system roles. nullable: true created_by: type: string format: uuid description: The user who created the role. `null` for system roles. nullable: true 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 responses: ValidationError: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: VALIDATION_ERROR message: Missing required field or invalid value. 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.