Authentication

There are two ways into the API. Password accounts sign in directly and get a token. Accounts created through social sign-in (Google/GitHub via Clerk) have no password — they exchange a Clerk session token for the same kind of token. Either way, every API request after that is authenticated identically.

Sign up

curl -X POST $BASE/signup \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "YourPass123"}'

{ "access_token": "eyJhbGciOi…", "token_type": "bearer" }

Passwords must be 8–100 characters with at least one letter and one number. Signing up also signs you in — the response carries a token, and a Set-Cookie header sets it as an HTTP-only cookie.

Sign in

curl -X POST $BASE/signin \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "YourPass123"}'

Same response shape as /signup.

Authenticating requests

The token works two ways — pick whichever suits your client:

Bearer header (simplest for scripts):

TOKEN=$(curl -s -X POST $BASE/signin \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "YourPass123"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

curl -H "Authorization: Bearer $TOKEN" $BASE/users/me

Cookie jar (mirrors how the browser works):

curl -c cookies.txt -X POST $BASE/signin \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "YourPass123"}'

curl -b cookies.txt $BASE/users/me

Tokens expire after 24 hours — on a 401, sign in again. Long-running automations should catch 401s and re-authenticate rather than assume a session lives forever.

Clerk sessions

If your account was created through social sign-in, there’s no password to POST /signin with. Instead, exchange the Clerk session token your frontend holds for an Insight AI session:

curl -X POST $BASE/auth/session \
  -H "Authorization: Bearer <clerk-session-token>" \
  -c cookies.txt

The response is your user record, and the Set-Cookie header carries the same 24-hour access_token cookie the password flow issues. Clerk tokens are not accepted on ordinary endpoints — exchange first, then call the API with the cookie (or keep using a password-based service account for automation, which is simpler).

A 503 from this endpoint means the instance has no Clerk configured; password sign-in still works there.

Who am I?

curl -b cookies.txt $BASE/users/me

Returns your user record (id, email, display_name, avatar_url, timestamps — the last two are filled in for social sign-ins). Other user endpoints: GET /users lists users, GET /users/{id}/user_groups shows a user’s group.

Sign out

curl -b cookies.txt -X POST $BASE/signout

Clears the cookie. Bearer tokens simply expire on their own.