ApiKey
Represents an API key for programmatic access to the system. API keys allow applications, scripts, or services to authenticate without using username/password combinations. They're essential for machine-to-machine communication, continuous integration, automated scripts, and third-party integrations. Each API key has a unique identifier, can be restricted by IP address or domain, has configurable permissions, and includes rate limiting to prevent abuse. API keys can be revoked instantly if compromised, and their usage is tracked for security auditing. Unlike user sessions, API keys don't expire automatically but can have validity periods set. They're typically used in HTTP headers or query parameters for authentication.
Properties
| Property | Type | Mode | Description | Required |
|---|---|---|---|---|
| apiKeyId | uuid | stored | Unique identifier for this API key | Required |
| keyHash | string | stored | Cryptographically hashed version of the actual key | Required |
| keyPrefix | string | stored | Visible prefix to identify the key (first few characters) Example: | Required |
| name | string | stored | Human-friendly name to identify the key's purpose Example: | Required |
| description | string | stored | Detailed description of what this key is used for | Optional |
| type | string | enum | Classification of the API key Values: Example: | Optional |
| userId | uuid | stored | User who created and owns this key | Optional |
| organizationId | uuid | stored | Organization that owns this key | Optional |
| validFrom | DateTime | stored | When the key becomes valid | Required |
| validUntil | DateTime | stored | When the key expires (null for never) | Optional |
| lastUsedAt | DateTime | stored | Last time this key was used in an API request | Optional |
| lastUsedIp | string | stored | IP address from last use | Optional |
| usageCount | bigint | stored | Total number of API calls made with this key | Optional |
| isActive | boolean | stored | Whether the key is currently usable | Optional |
| revokedAt | DateTime | stored | When the key was revoked (if applicable) | Optional |
| revokedBy | uuid | stored | User who revoked the key | Optional |
| revokedReason | string | stored | Explanation for why the key was revoked | Optional |
| createdAt | DateTime | stored | When the key was generated | Required |
| createdBy | uuid | stored | User who created the key | Optional |
Examples
Example 1
{
"@type": "ApiKey",
"apiKeyId": "key_550e8400",
"keyPrefix": "sk_live_4Xb9",
"name": "Production E-commerce Integration",
"description": "Used by our e-commerce platform to sync inventory and process orders",
"type": "secret",
"userId": "user_123",
"validFrom": "2024-01-01T00:00:00Z",
"validUntil": null,
"lastUsedAt": "2024-03-15T14:30:00Z",
"lastUsedIp": "203.0.113.42",
"usageCount": 15420,
"isActive": true,
"createdAt": "2024-01-01T00:00:00Z"
}Example 2
{
"@type": "ApiKey",
"apiKeyId": "key_test_999",
"keyPrefix": "sk_test_7Yz2",
"name": "Development Testing Key",
"description": "Temporary key for integration testing",
"type": "test",
"userId": "developer_456",
"validFrom": "2024-03-01T00:00:00Z",
"validUntil": "2024-04-01T00:00:00Z",
"lastUsedAt": "2024-03-14T10:00:00Z",
"lastUsedIp": "10.0.0.50",
"usageCount": 250,
"isActive": false,
"revokedAt": "2024-03-15T00:00:00Z",
"revokedBy": "admin_789",
"revokedReason": "Key was accidentally committed to public repository",
"createdAt": "2024-03-01T00:00:00Z"
}