Authentication

Embedd.to uses two authentication methods depending on the operation.

API Key Authentication

Most API requests use an API key. Keys are prefixed with sk_ and included in the Authorization header:

curl -H "Authorization: Bearer sk_your_api_key" \
  https://api.embedd.to/v1/connections

API key auth is used for all resource operations: connections, embedding providers, vector tables, queries, sync, environments, and API key management.

Permissions

API keys have one of two permission levels:

Permission	Allowed Operations
full	All operations — create, read, update, delete, query
read_only	GET requests and POST /query (semantically a read)

A read_only key attempting a mutating operation (POST, PUT, DELETE) receives a 403 Forbidden — except for POST /v1/vector-tables/{id}/query, which is allowed because querying is a read operation.

JWT Authentication (Passwordless OTP)

Organization management endpoints use JWT tokens obtained via passwordless OTP:

# 1. Request a code
curl -X POST https://api.embedd.to/v1/auth/otp \
  -d '{"email": "you@company.com"}'

# 2. Verify the code → get a JWT
curl -X POST https://api.embedd.to/v1/auth/verify \
  -d '{"email": "you@company.com", "code": "85056034"}'

# 3. Use the JWT for org management
curl -X POST https://api.embedd.to/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -d '{"name": "my-org"}'

JWTs expire after 1 hour. Use POST /v1/auth/refresh with your refresh token to get a new one without re-entering a code. See Auth API Reference for details.

JWT auth is used for:

• Creating, viewing, and deleting organizations
• Managing members (list, remove, leave, transfer ownership)
• Managing invitations (create, list, accept)

These endpoints operate on user identity and org membership, not on resources within an environment.

Environment Scoping

API key requests are scoped to an environment via the X-Environment-Id header:

curl -H "Authorization: Bearer sk_your_api_key" \
  -H "X-Environment-Id: env_abc123" \
  https://api.embedd.to/v1/connections

If the header is omitted, the request defaults to the prod environment.

Resources (connections, vector tables, embedding providers) are isolated per environment — a connection in dev is not visible in prod.

Auth Summary

Endpoint Category	Auth Method	Header
Organizations, members, invitations	Supabase JWT	Authorization: Bearer <jwt>
Everything else	API key	Authorization: Bearer sk_...
Environment selection	—	X-Environment-Id: <env_id> (optional, defaults to prod)

Security

• API keys are hashed using SHA-256 before storage — plaintext keys are never stored
• Connection credentials are encrypted at rest using AES-256
• API keys can be revoked immediately via DELETE /v1/api-keys/{id}
• Rate limits are enforced per-organization (see Rate Limiting)