Authentication

API Key Authentication

External Platform API endpoints such as /v1/platform/evaluations and /v1/platform/health require a valid API key in the Authorization header using the Bearer scheme:

curl https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..."

Key Format

All API keys use the prefix tf_platform_ followed by a random string.

Key Security

• API keys are hashed with bcrypt before storage. The raw key is only shown once at creation.
• Store keys in environment variables, never in source code.
• Rotate keys regularly using the key rotation endpoint.

Key Management

Management endpoints such as /v1/platform/workspaces, /v1/platform/api-keys, /v1/platform/webhooks, and /v1/platform/usage are internal management APIs in the current MVP. They are intended for TutorFlow-authenticated admin contexts, not for Platform API key authentication.

Create a Key

curl -X POST https://api.tutorflow.io/v1/platform/api-keys \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "workspaceId": "uuid-here"
  }'

Revoke a Key

curl -X POST https://api.tutorflow.io/v1/platform/api-keys/KEY_ID/revoke \
  -H "Authorization: Bearer tf_platform_..."

Rotate a Key

Rotation atomically revokes the old key and creates a new one with the same configuration:

curl -X POST https://api.tutorflow.io/v1/platform/api-keys/KEY_ID/rotate \
  -H "Authorization: Bearer tf_platform_..."

Error Responses

Invalid or missing API key:

{
  "error": {
    "code": "platform_invalid_api_key",
    "message": "Invalid or missing Platform API key",
    "status": 401
  }
}

Rate limit exceeded:

{
  "error": {
    "code": "platform_rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "status": 429
  }
}