API Keys

Programmatic access to the SapienStream platform. Generate and manage API keys for machine-to-machine communication, integrations, and automated workflows with comprehensive usage analytics.

13 FeaturesReal-Time AnalyticsQuota ManagementScoped Permissions

Overview

Key Management

  • • Create/Delete: Generate and revoke keys
  • • Scoped Access: Limit permissions per key
  • • Expiration: Optional time-limited keys
  • • Regenerate: Rotate keys without downtime
  • • Rate Limiting: Per-key request limits

Analytics & Monitoring

  • • Usage Tracking: Requests per key/endpoint
  • • Quota Status: Real-time remaining calls
  • • Organization Usage: Aggregate metrics
  • • Analytics Summary: Dashboard integration
  • • WebSocket Updates: Live streaming data

API Key Data Model

API Key Properties
Complete API key structure with permissions and usage metadata
{
  "id": "key_abc123def456",
  "name": "Production Integration Key",
  "key_prefix": "sk_live_abc1",
  "description": "Used for automated data sync with ERP system",
  "scopes": ["machines:read", "tags:read", "tags:write"],
  "rate_limit": 1000,
  "rate_limit_period": "hour",
  "is_active": true,
  "expires_at": "2025-08-26T00:00:00Z",
  "last_used_at": "2024-08-26T14:30:00Z",
  "usage": {
    "total_requests": 45678,
    "requests_today": 234,
    "requests_this_month": 12456
  },
  "created_at": "2024-01-15T10:00:00Z",
  "created_by": "user_001"
}

Available Scopes

Machines
machines:readmachines:writemachines:delete
Tags
tags:readtags:writetags:delete
Components
components:readcomponents:write
Documents
documents:readdocuments:write
Data
data:ingestdata:export
Admin
admin:readadmin:write

Key Management

POST/v1/api-keysAuth Required
Create API Key
Generate a new API key with specified permissions and rate limits. The full key is only shown once upon creation.

Request Body

Requestjson
{
  "name": "ERP Integration Key",
  "description": "Automated sync with SAP system",
  "scopes": ["machines:read", "tags:read", "tags:write", "data:export"],
  "rate_limit": 1000,
  "rate_limit_period": "hour",
  "expires_at": "2025-12-31T23:59:59Z"
}

Response

Responsejson
{
  "id": "key_abc123def456",
  "name": "ERP Integration Key",
  "key": "sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234",
  "key_prefix": "sk_live_abc1",
  "scopes": ["machines:read", "tags:read", "tags:write", "data:export"],
  "rate_limit": 1000,
  "rate_limit_period": "hour",
  "is_active": true,
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2024-08-26T10:00:00Z"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Important: Save Your Key

The full API key is only displayed once at creation time. Store it securely - you won't be able to retrieve it again.

GET/v1/api-keysAuth Required
List API Keys
Retrieve all API keys for the current user's organization.

Parameters

is_activeboolean

Filter by active status

limitinteger

Max results (default: 50)

Response

Responsejson
[
  {
    "id": "key_abc123",
    "name": "Production Integration",
    "key_prefix": "sk_live_abc1",
    "scopes": ["machines:read", "tags:read"],
    "is_active": true,
    "last_used_at": "2024-08-26T14:30:00Z",
    "created_at": "2024-01-15T10:00:00Z"
  },
  {
    "id": "key_def456",
    "name": "Development Key",
    "key_prefix": "sk_test_def4",
    "scopes": ["machines:read"],
    "is_active": true,
    "last_used_at": null,
    "created_at": "2024-08-01T09:00:00Z"
  }
]

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/{api_key_id}Auth Required
Get API Key Details
Retrieve detailed information about a specific API key.

Parameters

api_key_idstringRequired

API key identifier

Response

Responsejson
{
  "id": "key_abc123",
  "name": "Production Integration",
  "key_prefix": "sk_live_abc1",
  "description": "Used for automated data sync",
  "scopes": ["machines:read", "tags:read", "tags:write"],
  "rate_limit": 1000,
  "rate_limit_period": "hour",
  "is_active": true,
  "expires_at": "2025-08-26T00:00:00Z",
  "last_used_at": "2024-08-26T14:30:00Z",
  "created_at": "2024-01-15T10:00:00Z",
  "created_by": "user_001"
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/{api_key_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
PUT/v1/api-keys/{api_key_id}Auth Required
Update API Key
Modify API key settings including name, scopes, rate limits, and expiration.

Request Body

Requestjson
{
  "name": "Production Integration v2",
  "scopes": ["machines:read", "tags:read", "tags:write", "data:ingest"],
  "rate_limit": 2000,
  "is_active": true
}

Response

Responsejson
{
  "id": "key_abc123",
  "name": "Production Integration v2",
  "key_prefix": "sk_live_abc1",
  "scopes": ["machines:read", "tags:read", "tags:write", "data:ingest"],
  "rate_limit": 2000,
  "is_active": true,
  "updated_at": "2024-08-26T15:00:00Z"
}

Try it out

cURLbash
curl -X PUT "https://sapienstream.com/api/v1/api-keys/{api_key_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
DELETE/v1/api-keys/{api_key_id}Auth Required
Delete API Key
Permanently revoke and delete an API key. This action cannot be undone.

Parameters

api_key_idstringRequired

API key identifier

Response

Responsejson
{
  "success": true,
  "message": "API key deleted successfully"
}

Try it out

cURLbash
curl -X DELETE "https://sapienstream.com/api/v1/api-keys/{api_key_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/v1/api-keys/{api_key_id}/regenerateAuth Required
Regenerate API Key
Generate a new key value while keeping the same settings. Useful for key rotation without reconfiguring permissions.

Parameters

api_key_idstringRequired

API key identifier

Response

Responsejson
{
  "id": "key_abc123",
  "name": "Production Integration",
  "key": "sk_live_xyz789abc012def345ghi678jkl901mno234pqr567stu890",
  "key_prefix": "sk_live_xyz7",
  "scopes": ["machines:read", "tags:read", "tags:write"],
  "regenerated_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/api-keys/{api_key_id}/regenerate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Usage Analytics

GET/v1/api-keys/{api_key_id}/usageAuth Required
Get Key Usage
Retrieve detailed usage statistics for a specific API key.

Parameters

api_key_idstringRequired

API key identifier

periodstring

Time period (day, week, month)

Response

Responsejson
{
  "api_key_id": "key_abc123",
  "period": "month",
  "total_requests": 12456,
  "successful_requests": 12234,
  "failed_requests": 222,
  "rate_limited_requests": 45,
  "endpoints": [
    {"path": "/machines", "method": "GET", "count": 5678},
    {"path": "/tags", "method": "GET", "count": 4321},
    {"path": "/tags/write", "method": "POST", "count": 2457}
  ],
  "daily_breakdown": [
    {"date": "2024-08-26", "requests": 456},
    {"date": "2024-08-25", "requests": 423}
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/{api_key_id}/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/organization/usageAuth Required
Get Organization Usage
Aggregate usage metrics across all API keys in the organization.

Parameters

periodstring

Time period (day, week, month)

Response

Responsejson
{
  "organization_id": "org_001",
  "period": "month",
  "total_keys": 5,
  "active_keys": 4,
  "total_requests": 89234,
  "requests_by_key": [
    {"key_id": "key_abc123", "name": "Production", "requests": 45678},
    {"key_id": "key_def456", "name": "Development", "requests": 23456}
  ],
  "top_endpoints": [
    {"path": "/machines", "requests": 34567},
    {"path": "/tags", "requests": 28901}
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/organization/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/billing/usage-by-keyAuth Required
Usage by Key (Billing)
Comparative usage analysis across all keys for billing purposes.

Response

Responsejson
{
  "billing_period": "2024-08",
  "keys": [
    {
      "key_id": "key_abc123",
      "name": "Production",
      "requests": 45678,
      "data_transferred_mb": 234.5,
      "estimated_cost": 12.50
    },
    {
      "key_id": "key_def456",
      "name": "Development",
      "requests": 23456,
      "data_transferred_mb": 89.2,
      "estimated_cost": 5.75
    }
  ],
  "total_estimated_cost": 18.25
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/billing/usage-by-key" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/analytics/summaryAuth Required
Analytics Summary
Dashboard-ready analytics summary with key metrics and trends.

Response

Responsejson
{
  "period": "month",
  "total_requests": 89234,
  "growth_percent": 12.5,
  "avg_response_time_ms": 145,
  "error_rate_percent": 1.8,
  "most_active_key": {
    "key_id": "key_abc123",
    "name": "Production",
    "requests": 45678
  },
  "trends": {
    "requests": [{"date": "2024-08-20", "value": 3456}, ...],
    "errors": [{"date": "2024-08-20", "value": 45}, ...]
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/analytics/summary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/quota/statusAuth Required
Quota Status
Check remaining API quota allocation and usage limits.

Response

Responsejson
{
  "plan": "professional",
  "quota": {
    "requests_per_month": 100000,
    "used": 89234,
    "remaining": 10766,
    "percent_used": 89.2
  },
  "rate_limits": {
    "requests_per_minute": 100,
    "current_usage": 45
  },
  "alerts": [
    {
      "type": "quota_warning",
      "message": "You've used 89% of your monthly API quota",
      "threshold": 80
    }
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/quota/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/api-keys/me/limitsAuth Required
My Limits
Get the current user's personal API key limits and permissions.

Response

Responsejson
{
  "user_id": "user_001",
  "max_keys": 10,
  "current_keys": 4,
  "available_scopes": [
    "machines:read", "machines:write",
    "tags:read", "tags:write",
    "components:read", "documents:read"
  ],
  "max_rate_limit": 2000,
  "can_create_admin_keys": false
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/api-keys/me/limits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Key Testing

POST/v1/api-keys/test
Test API Key
Validate that an API key is working correctly and has the expected permissions.

Request Body

Requestjson
{
  "api_key": "sk_live_abc123def456..."
}

Response

Responsejson
{
  "valid": true,
  "key_id": "key_abc123",
  "name": "Production Integration",
  "scopes": ["machines:read", "tags:read", "tags:write"],
  "rate_limit": {
    "limit": 1000,
    "remaining": 856,
    "reset_at": "2024-08-26T15:00:00Z"
  },
  "expires_at": "2025-08-26T00:00:00Z",
  "is_expired": false
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/api-keys/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Using API Keys

Authentication Header
Include your API key in the X-API-Key header for all requests
curl -X GET "https://sapienstream.com/api/v1/machines" \
  -H "X-API-Key: sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234"

Python Example

import requests

API_KEY = "sk_live_abc123def456..."
BASE_URL = "https://sapienstream.com/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Get machines
response = requests.get(f"{BASE_URL}/machines", headers=headers)
machines = response.json()

# Write tag value
response = requests.put(
    f"{BASE_URL}/tags/{machine_id}/{tag_name}/write",
    headers=headers,
    json={"value": 42.5}
)