> ## 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 Virtual Key > Issue a virtual key for a project to a user or a service account. Provide exactly one of `user_id` or `service_account_id`. The user or service account must exist, be a direct member of the workspace, and be active. Each user or service account can hold one virtual key per project: a second request returns `409` with the existing key's `virtual_key_id` until that key is revoked. Use [Get Virtual Key](/en/API/Get-Virtual-Key) to inspect the existing key. A disabled key counts toward this limit; a revoked key does not, so a script can safely be re-run. The response contains the full key secret in `key`. The secret is returned only once and cannot be retrieved again, so store it securely. ## OpenAPI ````yaml en/API/Management-API.yaml POST /workspaces/{workspace_id}/projects/{project_id}/virtual-keys 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. 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: [] 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. paths: /workspaces/{workspace_id}/projects/{project_id}/virtual-keys: post: tags: - Virtual Keys summary: Create Virtual Key description: > Issue a virtual key for a project to a user or a service account. Provide exactly one of `user_id` or `service_account_id`. The user or service account must exist, be a direct member of the workspace, and be active. Each user or service account can hold one virtual key per project: a second request returns `409` with the existing key's `virtual_key_id` until that key is revoked. Use [Get Virtual Key](/en/API/Get-Virtual-Key) to inspect the existing key. A disabled key counts toward this limit; a revoked key does not, so a script can safely be re-run. The response contains the full key secret in `key`. The secret is returned only once and cannot be retrieved again, so store it securely. operationId: createVirtualKey parameters: - name: workspace_id in: path required: true description: Workspace identifier (UUID). schema: type: string format: uuid - name: project_id in: path required: true description: Project identifier (UUID). schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVirtualKeyRequest' example: service_account_id: c3d4e5f6-a7b8-9012-cdef-123456789012 name: ci-pipeline-key responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/VirtualKeyWithSecret' example: virtual_key_id: e5f6a7b8-c9d0-1234-efab-345678901234 key: REDACTED-FULL-KEY-SHOWN-ONCE last_four: x7Qa name: ci-pipeline-key key_type: service_account user_id: null service_account_id: c3d4e5f6-a7b8-9012-cdef-123456789012 workspace_id: f6a7b8c9-d0e1-2345-fabc-456789012345 project_id: a7b8c9d0-e1f2-3456-abcd-567890123456 status: active created_at: '2026-10-30T09:00:00Z' created_by: 00000000-0000-0000-0000-000000000001 revoked_at: null revoked_by: null '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request value: error: code: VALIDATION_ERROR message: Missing required field or invalid value. user_not_found: summary: User not found value: error: code: USER_NOT_FOUND message: The specified user does not exist. service_account_not_found: summary: Service account not found value: error: code: SERVICE_ACCOUNT_NOT_FOUND message: The specified service account does not exist. entity_not_in_workspace: summary: Not a direct member of the workspace value: error: code: ENTITY_NOT_IN_WORKSPACE message: >- The specified user or service account is not a direct member of this workspace. '403': $ref: '#/components/responses/VirtualKeyForbidden' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: workspace_not_found: summary: Workspace not found or caller is not a member value: error: code: WORKSPACE_NOT_FOUND message: The specified workspace does not exist. project_not_found: summary: Project not found value: error: code: PROJECT_NOT_FOUND message: The specified project does not exist. '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: already_exists: summary: >- Holder already has a virtual key for this project. Use the returned virtual_key_id with Get Virtual Key to inspect it. value: error: code: VIRTUAL_KEY_ALREADY_EXISTS message: >- A virtual key already exists for this user or service account in this project. details: - virtual_key_id: e5f6a7b8-c9d0-1234-efab-345678901234 '429': $ref: '#/components/responses/TooManyRequests' security: - oauth2: [] components: schemas: CreateVirtualKeyRequest: type: object properties: user_id: type: string format: uuid description: >- The user to issue the key to. Provide exactly one of `user_id` or `service_account_id`. service_account_id: type: string format: uuid description: >- The service account to issue the key to. Provide exactly one of `user_id` or `service_account_id`. name: type: string description: Display name of the virtual key. VirtualKeyWithSecret: allOf: - $ref: '#/components/schemas/VirtualKey' - type: object properties: key: type: string description: >- The full virtual key secret. Returned only in the create response and cannot be retrieved again. 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 VirtualKey: type: object properties: virtual_key_id: type: string format: uuid description: Virtual key identifier. last_four: type: string description: >- The last four characters of the virtual key. Use it to identify a key. The full secret is never returned after creation. name: type: string nullable: true description: Display name of the virtual key. key_type: type: string enum: - user - service_account description: The type of identity the key is issued to. user_id: type: string format: uuid nullable: true description: >- The user the key is issued to. null when `key_type` is `service_account`. service_account_id: type: string format: uuid nullable: true description: >- The service account the key is issued to. null when `key_type` is `user`. workspace_id: type: string format: uuid description: The workspace the key belongs to. project_id: type: string format: uuid description: The project the key is issued for. status: type: string enum: - active - disabled - revoked description: Current state of the key. Revoked is permanent. created_at: type: string format: date-time description: ISO 8601 UTC. created_by: type: string format: uuid description: ID of the caller that created the key. revoked_at: type: string format: date-time nullable: true description: ISO 8601 UTC. null unless the key is revoked. revoked_by: type: string format: uuid nullable: true description: >- ID of the caller that revoked the key. null unless the key is revoked. responses: VirtualKeyForbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_role: summary: Caller has a role that cannot manage virtual keys value: error: code: INSUFFICIENT_ROLE message: Your role in this workspace does not permit this operation. caller_type_not_permitted: summary: Service account has no role in the workspace value: error: code: CALLER_TYPE_NOT_PERMITTED message: This caller type is not permitted to perform this operation. TooManyRequests: description: >- Too Many Requests. The account exceeded 600 Management API calls per minute. headers: Retry-After: description: Number of seconds to wait before you retry the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: oauth2: type: oauth2 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.