Skip to main content

Account Setup

Get from zero to your first API call in four steps: authenticate, create an organization, store your API key, and start building.

1. Authenticate​

Embedd uses passwordless authentication. Provide your email and enter the verification code sent to your inbox.

Request a code:

curl -X POST https://api.embedd.to/v1/auth/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

Verify the code:

curl -X POST https://api.embedd.to/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "85056034"}'

Response:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "53bku3di52oi...",
  "expires_in": 3600,
  "token_type": "bearer"
}

The access_token is your JWT — valid for 1 hour. Use it to create an organization. When it expires, use the refresh endpoint to get a new one.

2. Create an Organization​

Organizations are the top-level container for all your resources. Create one using your JWT:

curl -X POST https://api.embedd.to/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-company"}'

Response:

{
  "organization": {
    "id": "org_abc123",
    "name": "my-company",
    "status": "active",
    "tier": "free",
    "created_at": "2026-03-13T10:00:00Z"
  },
  "api_key": "sk_live_abc123..."
}

This does three things:

  • Creates your organization on the free tier
  • Makes you the owner
  • Generates your first API key and returns it once — store it now

The api_key value is the raw key. It will never be shown again.

3. Store Your API Key​

From this point on, you use the API key for all resource operations — not the JWT.

Your API key is prefixed with sk_ and is used for all resource operations (connections, vector tables, queries). Include it in the Authorization header:

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

You can create additional API keys later via the API Keys endpoint.

What You Get​

After creating an organization, you have:

ResourceDetails
OrganizationOn the free tier (3 tables, 100K vectors, 25 RPM)
Your roleOwner (full permissions)
API keyOne full permission key
Environmentprod (created automatically, cannot be deleted)

Environments​

The prod environment is created automatically. All resources are scoped to an environment via the X-Environment-Id header. If you omit the header, requests default to prod.

To create additional environments (e.g., for development or staging):

curl -X POST https://api.embedd.to/v1/environments \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "dev"}'

See Environments API Reference for details.

Inviting Team Members​

Owners and admins can invite others to the organization:

curl -X POST https://api.embedd.to/v1/organizations/org_abc123/invitations \
  -H "Authorization: Bearer YOUR_SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@company.com", "role": "admin"}'

Invitations expire after 7 days. See Organizations API Reference for the full invitation flow.

Next Steps​