Authentication

API Key Authentication

External Platform API endpoints such as /v1/platform/evaluations and /v1/platform/health require a valid Platform 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 through the TutorFlow dashboard.

Key Management

Workspace, key, webhook, usage, and billing management endpoints are internal management APIs in the current MVP. They are authenticated with TutorFlow admin auth, not Platform API keys, and are intentionally not documented as public agent API surface. A request signed with Authorization: Bearer tf_platform_... will not work for those endpoints.

Autonomous agents should get their first API key with POST /v1/platform/agent/register. Human operators should create and rotate keys through the TutorFlow dashboard, which calls the dashboard admin-auth endpoints on their behalf.

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