Auth

Passwordless authentication via email OTP. These endpoints do not require an API key or JWT — they are the entry point for new and returning users.

Endpoints

Method	Path	Description
POST	/v1/auth/otp	Send a verification code
POST	/v1/auth/verify	Verify code, get tokens
POST	/v1/auth/refresh	Refresh an expired token

---

Send Verification Code

POST /v1/auth/otp

Sends a one-time verification code to the given email address. If the email is new, a user account is created automatically.

Auth: None

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

Field	Required	Type	Description
email	Yes	string	Email address to send the code to

Response (200):

{
  "message": "Verification code sent to you@company.com"
}

Check your inbox for the code. Codes are single-use.

---

Verify Code

POST /v1/auth/verify

Verifies the OTP code and returns an access token (JWT) and refresh token.

Auth: None

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

Field	Required	Type	Description
email	Yes	string	The email the code was sent to
code	Yes	string	The verification code (6-8 digits)

Response (200):

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

The access_token is a JWT valid for 1 hour. Use it in the Authorization header for organization management endpoints.

Errors:

Status	Reason
400	Supabase rejected the request
401	Invalid or expired code

---

Refresh Token

POST /v1/auth/refresh

Exchanges a refresh token for a new access token. Use this when the JWT expires instead of asking the user to re-enter a code.

Auth: None

curl -X POST https://api.embedd.to/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "53bku3di52oi..."}'

Field	Required	Type	Description
refresh_token	Yes	string	The refresh token from a previous verify or refresh

Response (200):

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

Both the access token and refresh token are rotated on each refresh.

Errors:

Status	Reason
401	Invalid or expired refresh token

---

When Do I Need a JWT?

The JWT is only needed for organization management:

• Creating, viewing, and deleting organizations
• Managing members and invitations
• Transferring ownership

For all other operations (connections, vector tables, queries, sync), use an API key instead.