ApiKeyScope

Defines the specific permissions and access boundaries for API keys using OAuth-style scope patterns. Scopes are a way to limit what an API key can do in your system, following the principle of least privilege - each key should only have the minimum permissions needed for its task. This entity breaks down scopes into resource and action pairs, like 'users:read' or 'orders:write', making it clear what operations are allowed on which resources. This granular control is essential for security when providing API access to third-party developers, automated scripts, or microservices. Each scope can include additional constraints in JSON format, such as limiting access to specific record IDs, IP ranges, or time windows. The system can combine multiple scopes to create precise permission sets - for example, an e-commerce integration might have 'products:read', 'inventory:write', and 'orders:create' but not 'users:delete'. Scopes make it easy to audit what each API key can access and quickly revoke specific permissions without regenerating the entire key. This pattern is widely used in modern APIs like GitHub, Google, and Stripe to provide secure, controlled access.

12 properties

Schema

Properties

Property	Type	Mode	Description	Required
apiKeyId	uuid	stored	The API key this scope belongs to	Required
scope	string	stored	Full scope string in resource:action format Example: `"users:read"`	Required
resource	string	stored	The resource or entity this scope applies to Example: `"users"`	Required
action	string	stored	The allowed action on the resource Example: `"read"`	Required
constraints	string	stored	Additional limitations in JSON format (filters, conditions) Example: `"{\"organization_id\": \"org_123\", \"max_results\": 100}"`	Optional
description	string	stored	Human-readable explanation of what this scope allows Example: `"Read access to user profiles within the organization"`	Optional
isActive	boolean	stored	Whether this scope is currently enforced	Optional
expiresAt	DateTime	stored	When this scope expires and is no longer valid	Optional
grantedAt	DateTime	stored	When this scope was added to the API key	Required
grantedBy	User	stored	User who granted this scope	Optional
lastUsedAt	DateTime	stored	Last time this scope was checked during an API call	Optional
usageCount	integer	stored	Number of times this scope has been used	Optional

Examples

Example 1

{
  "@type": "ApiKeyScope",
  "apiKeyId": "key_550e8400",
  "scope": "orders:write",
  "resource": "orders",
  "action": "write",
  "constraints": "{\"status\": [\"pending\", \"processing\"], \"max_amount\": 10000}",
  "description": "Create and update orders up to $10,000 in pending or processing status",
  "isActive": true,
  "expiresAt": null,
  "grantedAt": "2024-01-15T10:00:00Z",
  "grantedBy": "admin_123",
  "lastUsedAt": "2024-03-15T14:30:00Z",
  "usageCount": 1847
}

Example 2

{
  "@type": "ApiKeyScope",
  "apiKeyId": "key_analytics_789",
  "scope": "analytics:read",
  "resource": "analytics",
  "action": "read",
  "constraints": "{\"date_range\": \"last_90_days\", \"metrics\": [\"revenue\", \"users\", \"conversion\"]}",
  "description": "Read-only access to revenue, user, and conversion analytics for the last 90 days",
  "isActive": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "grantedAt": "2024-03-01T08:00:00Z",
  "grantedBy": "manager_456",
  "lastUsedAt": "2024-03-15T09:00:00Z",
  "usageCount": 523
}