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

PropertyTypeModeDescriptionRequired
apiKeyIduuid
stored

The API key this scope belongs to

Required
scopestring
stored

Full scope string in resource:action format

Example: "users:read"

Required
resourcestring
stored

The resource or entity this scope applies to

Example: "users"

Required
actionstring
stored

The allowed action on the resource

Example: "read"

Required
constraintsstring
stored

Additional limitations in JSON format (filters, conditions)

Example: "{\"organization_id\": \"org_123\", \"max_results\": 100}"

Optional
descriptionstring
stored

Human-readable explanation of what this scope allows

Example: "Read access to user profiles within the organization"

Optional
isActiveboolean
stored

Whether this scope is currently enforced

Optional
expiresAtDateTime
stored

When this scope expires and is no longer valid

Optional
grantedAtDateTime
stored

When this scope was added to the API key

Required
grantedByUser
stored

User who granted this scope

Optional
lastUsedAtDateTime
stored

Last time this scope was checked during an API call

Optional
usageCountinteger
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
}