> ## 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. # Update API key status > Update the status of an API key. REVOKED is a terminal state. ## OpenAPI ````yaml /api-reference/v1/api-keys-v1.yaml patch /api-keys/{api_key_id} 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/{api_key_id}: patch: tags: - API Keys summary: Update API key status description: Update the status of an API key. REVOKED is a terminal state. operationId: updateApiKeyStatus parameters: - name: api_key_id in: path required: true schema: type: string pattern: ^[0-9A-Z]{26}$ description: API key resource ID (ULID, 26 characters) example: 01HX2ABC3DEF4GHI5JKL6MNO7P requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateApiKeyRequest' examples: revokeKey: $ref: '#/components/examples/UpdateApiKeyRevoke' suspendKey: $ref: '#/components/examples/UpdateApiKeySuspend' reactivateKey: $ref: '#/components/examples/UpdateApiKeyReactivate' responses: '200': description: API key status updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateApiKeyResponse' examples: updated: $ref: '#/components/examples/ApiKeyUpdated' '400': description: Invalid status transition or request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidTransition: $ref: '#/components/examples/InvalidTransitionError' invalidStatus: $ref: '#/components/examples/InvalidStatusError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/PermissionDenied' '404': description: API key not found or belongs to different organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/ApiKeyNotFoundError' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: UpdateApiKeyRequest: type: object required: - status description: Update the status of an API key. properties: status: $ref: '#/components/schemas/ApiKeyStatus' reason: type: string nullable: true description: Reason for the status change (for audit purposes) maxLength: 2000 example: Key compromised, revoking as a precaution UpdateApiKeyResponse: type: object required: - api_key properties: api_key: $ref: '#/components/schemas/ApiKeyResource' 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 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 ApiKeyResource: type: object description: API key resource. Key values are masked except 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 API key value (masked except during creation). example: '****-****-****-a1b2' 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: '2025-10-15T14:30:00Z' last_used_at: type: string format: date-time nullable: true description: Timestamp of last API key usage (ISO 8601) example: '2025-10-16T09:15:00Z' 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:* examples: UpdateApiKeyRevoke: summary: Revoke an API key description: Permanently revoke a key (terminal state, cannot be undone). value: status: REVOKED reason: Key compromised, revoking as a precaution UpdateApiKeySuspend: summary: Suspend an API key description: Temporarily disable a key. Can be reactivated later. value: status: SUSPENDED reason: Temporarily disabling for security audit UpdateApiKeyReactivate: summary: Reactivate a suspended or expired key description: Reactivate a key that was previously suspended or expired. value: status: ACTIVE reason: Security audit complete, reactivating key ApiKeyUpdated: summary: API key status updated successfully (masked) value: api_key: id: 01HX2ABC3DEF4GHI5JKL6MNO7P organization_id: caf26438 api_key: '****-****-****-o5p6' key_type: SERVICE status: REVOKED name: Production Service Key description: Primary key for production backend service authentication permissions: [] create_time: '2025-10-14T12:00:00Z' update_time: '2025-10-23T16:45:00Z' last_used_at: '2025-10-16T09:15:00Z' InvalidTransitionError: summary: Invalid status transition value: error: code: INVALID_ARGUMENT message: Invalid status transition details: - field: status description: >- Cannot transition from REVOKED to ACTIVE. REVOKED is a terminal state. InvalidStatusError: summary: Invalid status value value: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: status description: Input should be 'ACTIVE', 'REVOKED', 'SUSPENDED', or 'EXPIRED' ApiKeyNotFoundError: summary: API key not found value: error: code: NOT_FOUND message: API key not found details: - field: api_key_id description: API key not found or not accessible by your organization 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 ````