> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create API key > Create a new API key. The full key value is only returned once in this response. ## OpenAPI ````yaml /api-reference/v1/api-keys-v1.yaml post /api-keys openapi: 3.0.3 info: title: Coval API Keys API version: 1.0.0 description: | Manage API keys for authenticating with the Coval platform. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: API Keys description: Manage API keys for your organization paths: /api-keys: post: tags: - API Keys summary: Create API key description: >- Create a new API key. The full key value is only returned once in this response. operationId: createApiKey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyRequest' examples: minimal: $ref: '#/components/examples/CreateApiKeyMinimal' withName: $ref: '#/components/examples/CreateApiKeyWithName' restrictedPermissions: $ref: '#/components/examples/CreateApiKeyRestrictedPermissions' responses: '201': description: API key created successfully content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyResponse' examples: created: $ref: '#/components/examples/ApiKeyCreated' '400': description: Invalid request body or validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidKeyType: $ref: '#/components/examples/InvalidKeyTypeError' nameTooLong: $ref: '#/components/examples/NameTooLongError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/PermissionDenied' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: CreateApiKeyRequest: type: object properties: name: type: string nullable: true description: Human-readable name for the API key maxLength: 200 example: Production Service Key description: type: string nullable: true description: Detailed description of the API key purpose maxLength: 2000 example: Primary key for production backend service authentication key_type: allOf: - $ref: '#/components/schemas/KeyType' default: SERVICE permissions: type: array description: >- Permission scopes to grant. Empty array (default) grants full access. items: $ref: '#/components/schemas/PermissionScope' default: [] example: [] CreateApiKeyResponse: type: object required: - api_key properties: api_key: $ref: '#/components/schemas/ApiKeyResourceUnmasked' ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Error code enum enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field name that caused the error example: status description: type: string description: Detailed error description example: Invalid status value KeyType: type: string description: > Type of API key. - **SERVICE**: Machine-to-machine authentication for backend services and integrations - **USER**: User-scoped key tied to individual user actions enum: - SERVICE - USER example: SERVICE PermissionScope: type: string description: > Permission scope. Format: resource:action, resource:*, or * for full access. Empty array [] grants full access. enum: - '*' - runs:read - runs:write - runs:* - agents:read - agents:write - agents:* - conversations:read - conversations:submit - conversations:* - metrics:read - metrics:* - test-sets:read - test-sets:write - test-sets:* - test-cases:read - test-cases:write - test-cases:* - personas:read - personas:write - personas:delete - personas:* - simulations:read - simulations:write - simulations:* - traces:read - traces:* - dashboards:read - dashboards:write - dashboards:delete - dashboards:* - api-keys:read - api-keys:write - api-keys:delete - api-keys:* - scheduled-runs:read - scheduled-runs:write - scheduled-runs:delete - scheduled-runs:* - run-templates:read - run-templates:write - run-templates:delete - run-templates:* - reports:read - reports:write - reports:delete - reports:* ApiKeyResourceUnmasked: type: object description: API key resource with full key value. Only returned during creation. properties: id: type: string description: API key resource ID (ULID, 26 characters) pattern: ^[0-9A-Z]{26}$ example: 01HX2ABC3DEF4GHI5JKL6MNO7P organization_id: type: string description: Organization ID that owns this API key example: caf26438 api_key: type: string description: >- The full API key value. Store it securely -- it cannot be retrieved again. example: coval_sk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 key_type: $ref: '#/components/schemas/KeyType' status: $ref: '#/components/schemas/ApiKeyStatus' name: type: string nullable: true description: Human-readable name for the API key maxLength: 200 example: Production Service Key description: type: string nullable: true description: Detailed description of the API key purpose maxLength: 2000 example: Primary key for production backend service authentication permissions: type: array description: > Permission scopes granted to this key. Empty array grants full access. See `PermissionScope` for valid values. items: $ref: '#/components/schemas/PermissionScope' example: [] create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: null last_used_at: type: string format: date-time nullable: true description: Timestamp of last API key usage (ISO 8601) example: null ApiKeyStatus: type: string description: | Current status of the API key. - **ACTIVE**: Key is active and can be used for authentication - **REVOKED**: Key has been permanently revoked (terminal state) - **SUSPENDED**: Key is temporarily disabled and can be reactivated - **EXPIRED**: Key has expired and can be reactivated enum: - ACTIVE - REVOKED - SUSPENDED - EXPIRED example: ACTIVE examples: CreateApiKeyMinimal: summary: Create API key with defaults description: Creates a SERVICE key with full access. All fields are optional. value: {} CreateApiKeyWithName: summary: Create named API key description: Create a service key with a descriptive name. value: name: Production Service Key description: Primary key for production backend service authentication CreateApiKeyRestrictedPermissions: summary: Create key with restricted permissions description: Create a user key with specific permission scopes. value: name: Read-Only Key description: Limited access key for reading runs, agents, and metrics key_type: USER permissions: - runs:read - agents:read - metrics:read ApiKeyCreated: summary: API key created successfully (unmasked) value: api_key: id: 01HX2ABC3DEF4GHI5JKL6MNO7P organization_id: caf26438 api_key: coval_sk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 key_type: SERVICE status: ACTIVE name: Production Service Key description: Primary key for production backend service authentication permissions: [] create_time: '2025-10-14T12:00:00Z' update_time: null last_used_at: null InvalidKeyTypeError: summary: Invalid key type value: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: key_type description: Input should be 'SERVICE' or 'USER' NameTooLongError: summary: Name exceeds maximum length value: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: name description: name must be at most 200 characters responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: X-API-Key description: Invalid or missing API key PermissionDenied: description: API key lacks required permission scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PERMISSION_DENIED message: Insufficient permissions details: - field: permissions description: 'API key does not have required permission: api-keys:write' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````