Authentication

Tusky supports two authentication methods: API keys for programmatic access and Clerk JWTs for browser-based sessions.

API keys

API keys are the primary way to authenticate with the Tusky API. They are prefixed with tdp_ for easy identification.

Creating a key

Create keys from the dashboard or via the API:

TypeScript
cURL

const key = await tusky.apiKeys.create({
  name: 'CI/CD Pipeline',
  scopes: ['files:write'],
  expiresInDays: 90,
});

// Save this — the full key is only shown once
console.log(key.key); // "tdp_abc123..."

curl -X POST https://api.opentusk.ai/api/auth/api-keys \
  -H "Authorization: Bearer tdp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "scopes": ["files:write"], "expiresInDays": 90}'

Using a key

Pass the key in the Authorization header:

Authorization: Bearer tdp_your_key_here

Key properties

Property	Description
Prefix	All keys start with `tdp_`
Storage	Server stores only `SHA-256(key)`
Expiry	Optional — keys can have an expiration date
Scopes	Optional — restrict what the key can do
Revocation	Immediate — sets `revoked_at` timestamp

Clerk JWT

Browser-based clients authenticate via Clerk JWTs. The JWT is passed in the same Authorization header:

Authorization: Bearer eyJhbGciOiJS...

This method is used by the Tusky web app and is not typically needed for API integrations.

Dev mode authentication

When running locally with TUSKY_ENV=development, the API accepts simplified auth:

Header	Description
`X-Dev-User-Id`	Authenticate as a specific user by database ID
`X-Dev-Clerk-Id`	Authenticate as a specific user by Clerk ID
(no header)	Falls back to the first user in the database

Error responses

Authentication failures return a 401 status:

{
  "error": "Unauthorized"
}

Using a revoked or expired key also returns 401.