Authentication

The Scribe Sight API uses API keys for authentication. All requests must include a valid API key in the Authorization header.

API Key Types

Key Type	Prefix	Permissions	Use Case
Secret	sk_live_	Full API access	Server-side integrations
Publishable	pk_live_	Upload initiation only	Client-side upload

Secret Key Security

Never expose your secret API key (sk_live_) in client-side code, public repositories, or browser JavaScript. Use publishable keys for client-side operations.

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

curl https://scribesight.com/api/v1/org \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Scopes

API keys support the following scopes:

Scope	Description
read	Read-only access to all resources
write	Full access (create, update, delete, trigger)

By default, secret keys have both read and write scopes.

Project-Scoped Keys

API keys can optionally be restricted to specific projects. When project IDs are specified:

• The key can only access resources within those projects
• Organization-level endpoints (like /v1/org) are still accessible
• Attempting to access other projects returns 403 Forbidden

Creating API Keys

Via Dashboard

Organization-level keys:

1. Navigate to Organizations → [Your Org] → Settings → API Keys
   • URL: scribesight.com/user/organizations/{org-slug}/settings/api-keys
2. Click Create API Key
3. Enter a name and select scopes
4. Copy your key — it's only shown once

Project-level keys:

1. Navigate to Organizations → [Your Org] → [Project] → Settings → API Keys
   • URL: scribesight.com/user/organizations/{org-slug}/{project-slug}/settings/api-keys
2. Click Create API Key
3. The key will automatically be scoped to that project

Via API

curl -X POST https://scribesight.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["read", "write"],
    "project_ids": ["proj_xxx"]
  }'

Response:

{
  "data": {
    "id": "key_xxxxxxxxxxxx",
    "name": "CI/CD Pipeline",
    "key_prefix": "sk_live_xxxx",
    "key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "scopes": ["read", "write"],
    "project_ids": ["proj_xxx"],
    "created_at": "2026-01-06T10:00:00Z"
  }
}

warning

The full API key is only returned once at creation time. Store it securely.

Revoking API Keys

curl -X DELETE https://scribesight.com/api/v1/api-keys/key_xxxxxxxxxxxx \
  -H "Authorization: Bearer sk_live_xxx"

Revoked keys immediately stop working. Any requests using the revoked key will receive 401 Unauthorized.

Key Rotation

To rotate an API key:

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Verify the new key is working
4. Revoke the old key

Errors

Error Code	Status	Description
authentication_required	401	Missing or invalid API key
insufficient_permissions	403	Key lacks required scope

Example Error:

{
  "error": {
    "code": "authentication_required",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "request_id": "req_xxxxxxxxxxxx"
  }
}

Best Practices

1. Use environment variables — Never hardcode API keys
2. Rotate keys regularly — Especially after team member departures
3. Use minimal scopes — Only request permissions you need
4. Monitor usage — Check the dashboard for unexpected activity
5. Use project scoping — Limit keys to specific projects when possible