Custom authentication

Architecture

Your UI collects the sign-in; your backend calls Curviate. Your API key never reaches a browser. Pass credentials straight through instead of storing them: Curviate uses them to connect the Account, never logs them and does not store them, unless you turn on Keep connected, which saves your login encrypted in the EU until you turn it off.

The flow: find a free seat, call POST /v1/auth/intent, walk your user through any checkpoint, then watch account status on a webhook.

Seats

Every connected account occupies one seat. GET /v1/accounts/seats lists them; an item with occupied false is free.

POST /v1/billing/seats/add with qty (1 to 50) buys more and returns the new seat_ids. Every call buys the seats it asks for, so retry only after checking the seat count. A Team on its free trial cannot add seats (TRIAL_ACTIVE_SEAT_LIMIT); buy a seat in the dashboard to convert first.

curl -X POST https://api.curviate.com/v1/billing/seats/add \
  -H "Authorization: Bearer $CURVIATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qty": 1}'

Credentials or cookie

Set auth_method:

Location: one of country, ip or proxy; strict unless allow_country_fallback: true.

Optional: products (allow-list of sales_navigator and recruiter), and linkedin_premium to pick Recruiter when an account holds both. timezone is deprecated and ignored: the zone follows the connection location.

Start the connect

curl -X POST https://api.curviate.com/v1/auth/intent \
  -H "Authorization: Bearer $CURVIATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seat_id": "seat_YOUR_FREE_SEAT_ID",
    "auth_method": "credentials",
    "credentials": { "email": "user@example.com", "password": "..." },
    "country": "US",
    "external_id": "usr_42"
  }'

Checkpoints

Every checkpoint call takes the account_id from the 202. A solve can chain into another 202, a poll into a 200 checkpoint_required; handle the new challenge_type the same way.

POST /v1/auth/checkpoint/request without challenge re-sends a code that never arrived; resent false means there was nothing to re-send, as with an authenticator app. TRY_ANOTHER_WAY as the code asks for another method, counting no attempt.

curl -X POST https://api.curviate.com/v1/auth/checkpoint/request \
  -H "Authorization: Bearer $CURVIATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_YOUR_ACCOUNT_ID", "challenge": "sms"}'

A CAPTCHA answers 422 with its challenge_type: connect with cookies instead.

Tag accounts with external_id

external_id is your id for the end user who owns the account: 1 to 255 characters, not unique, since one user may connect several accounts. Treat it as opaque. Do not put an email or other personal data in it; use your internal user id.

Set it on the intent, change it with PATCH /v1/accounts/{account_id} (null clears it), and list a user's accounts with GET /v1/accounts?external_id=usr_42. It comes back on account reads, the intent 202, the response that completes the connect, and every account webhook. The same PATCH stores metadata, a flat string map of up to 16 keys, replaced whole on each write.

Account status and the reconnect loop

POST /v1/webhooks with source account_status and no account_ids covers every current and future account; it reads back account_ids null. PATCH /v1/webhooks/{id} with account_ids null switches an existing one.

curl -X POST https://api.curviate.com/v1/webhooks \
  -H "Authorization: Bearer $CURVIATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "account_status", "request_url": "https://hooks.example.com/curviate"}'

Each event carries account_id, status and external_id, so you route it to your user without a lookup. Verify the signature first.

• account.reconnect_needed: the session expired or the credentials became invalid. Ask your user to sign in again, then call POST /v1/auth/intent with the account_id and fresh credentials or cookie. Checkpoints work as above.
• account.restricted: connected, but some actions fail. Tell your user; a reconnect may restore a failing premium product.
• account.disconnected: the account cannot act until reconnected.

GET /v1/accounts/{account_id} always has the current status. All events: Account status events.

Offboarding

DELETE /v1/accounts/{account_id} disconnects and deletes the account and frees its seat; a repeat call returns 200 with already_disconnected. Reuse the seat, or stop paying for it with POST /v1/billing/seats/{seat_id}/cancel, which ends it at effective_at, the end of the current period. POST /v1/billing/seats/{seat_id}/cancel/revert undoes that before then.

Errors

Branch on code. Full list: Errors.