API Keys

API keys are used to authenticate requests to the VKRA API. You can create multiple keys to scope access for different agents or environments.

API Key Endpoints

List API Keys

Retrieve a paginated list of API keys associated with your account.

GET /keys

Response Body

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Bot",
    "prefix": "at_live_",
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": "2024-01-15T12:00:00Z",
    "status": "active"
  }
]

Create API Key

Generate a new scoped API key. The full key is only shown once.

POST /keys

Request Body

{
  "name": "Development Bot"
}

Response Body

{
  "key": "at_live_abc123...",
  "metadata": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Development Bot",
    "prefix": "at_live_",
    "status": "active"
  }
}

Revoke API Key

Disable an API key without deleting it. It will no longer be usable for authentication.

POST /keys/{key_id}

Rotate API Key

Generate a new API key to replace an existing one. The old key is automatically revoked.

POST /keys/{key_id}/rotate

Delete API Key

Permanently delete an API key. This action cannot be undone.

DELETE /keys/{key_id}

Best Practices

1. Environment Scoping: Use separate keys for development, staging, and production.
2. Rotation: Periodically rotate your keys using the /rotate endpoint.
3. Naming: Use descriptive names (e.g., "Hugging Face Bot") to easily identify where each key is being used.
4. Security: Store your keys in secure environment variables or a secret management service.