Sign-in and sessions

The person's profile and preferences#

Response

Errors

Example

curl "https://api.ibel.ai/v1/auth/profile" \
  -H "Authorization: Bearer $SESSION"

Change the person's profile and preferences#

Any of name, avatar, language, time_zone, calendar, date_format, theme; null puts a field back on its default. Needs a dashboard session.

Request bodyapplication/json

• namestring | null
• avatarstring | null

  a png, jpeg or webp image as a data URL, under 40 KB

• languagestring | null

  one of fa, en, null

• time_zonestring | null

  an IANA time zone, for example Asia/Tehran

• calendarstring | null

  one of jalali, gregorian, null

• date_formatstring | null

  one of medium, short, long, null

• themestring | null

  one of system, light, dark, null

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/auth/profile" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"name":"my-api","avatar":"…","language":"fa","time_zone":"…","calendar":"jalali","date_format":"medium","theme":"system"}'

Begin changing the email address or mobile number#

Sends a code to the new address or number; nothing changes until it is confirmed. Needs a session and a fresh second factor (step_up_required).

Request bodyapplication/json

• channelstringrequired

  one of email, phone

• valuestringrequired

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/contact/start" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"channel":"email","value":"s3cr3t"}'

Finish changing the email address or mobile number#

With the code sent to the new one. Needs a session and a fresh second factor.

Request bodyapplication/json

• challengestringrequired
• codestringrequired

  pattern ^\d{6}$

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/contact/confirm" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"challenge":"…","code":"123456"}'

Send a sign-in code#

Same answer whether or not an account exists.

Request bodyapplication/json

• identifierstringrequired

  an email or an Iranian mobile

• browserstringrequired

  a random value of 16+ characters the client keeps

  at least 16 characters

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/signin" \
  -d '{"identifier":"you@example.com","browser":"b3f1c9a27d4e4c0e9a1f"}'

Exchange a sign-in code for a session#

Request bodyapplication/json

• challengestring (uuid)required
• codestringrequired

  pattern ^\d{6}$

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/verify" \
  -d '{"challenge":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","code":"123456"}'

Sign in with a magic link#

Request bodyapplication/json

• challengestring (uuid)required
• tokenstringrequired
• browserstringrequired

  a random value of 16+ characters the client keeps

  at least 16 characters

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/link" \
  -d '{"challenge":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","token":"…","browser":"b3f1c9a27d4e4c0e9a1f"}'

Whether sign-up is open#

CORS for the marketing site's origins (CH_SITE_ORIGINS), with the OPTIONS preflight.

Response

Errors

Example

curl "https://api.ibel.ai/v1/auth/registration"

Start a sign-up#

Request bodyapplication/json

• emailstringrequired
• phonestringrequired

  Iranian mobile

• browserstringrequired

  a random value of 16+ characters the client keeps

  at least 16 characters

• invitestring
• team_invitestring

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/signup" \
  -d '{"email":"you@example.com","phone":"09121234567","browser":"b3f1c9a27d4e4c0e9a1f"}'

Finish a sign-up#

Creates the person, their personal team and a session that is already stepped up.

Request bodyapplication/json

• email_challengestring (uuid)required
• email_codestringrequired
• phone_challengestring (uuid)required
• phone_codestringrequired
• invitestring
• team_invitestring

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/signup/verify" \
  -d '{"email_challenge":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","email_code":"…","phone_challenge":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","phone_code":"…"}'

Join the waitlist#

CORS for the marketing site's origins (CH_SITE_ORIGINS), with the OPTIONS preflight.

Request bodyapplication/json

• contactstringrequired

  an email or an Iranian mobile

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/waitlist" \
  -d '{"contact":"you@example.com"}'

The person's sessions#

Response

Errors

Example

curl "https://api.ibel.ai/v1/auth/sessions" \
  -H "Authorization: Bearer $SESSION"

End a session#

Parameters

• idstringpathrequired

  session id

  pattern ^[0-9a-f]{16}$

Response

Errors

Example

curl -X DELETE "https://api.ibel.ai/v1/auth/sessions/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $SESSION"

End this session#

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/signout" \
  -H "Authorization: Bearer $SESSION"

End every session of the person#

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/signout-everywhere" \
  -H "Authorization: Bearer $SESSION"

Factors and step-up methods#

Response

Errors

Example

curl "https://api.ibel.ai/v1/auth/factors" \
  -H "Authorization: Bearer $SESSION"

Send a step-up code#

Request bodyapplication/json

• methodstringrequired

  one of email, sms

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/step-up/start" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"method":"email"}'

Confirm the second factor#

Sensitive actions are then allowed for 10 minutes.

Request bodyapplication/json

• methodstring

  one of totp

• challengestring (uuid)
• codestringrequired

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/step-up/verify" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"code":"123456"}'

List your passkeys#

Response

Errors

Example

curl "https://api.ibel.ai/v1/auth/passkeys" \
  -H "Authorization: Bearer $SESSION"

Start adding a passkey#

Needs a fresh step-up.

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/passkeys/register/options" \
  -H "Authorization: Bearer $SESSION"

Finish adding a passkey#

Needs a fresh step-up.

Request bodyapplication/json

• challenge_idstring (uuid)required
• credentialobjectrequired

  what PublicKeyCredential.toJSON() returns: id, rawId, type, response

• namestring

  up to 60 characters

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/passkeys/register/verify" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"challenge_id":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","credential":{}}'

Remove a passkey#

Needs a fresh step-up.

Parameters

• idstring (uuid)pathrequired

Response

Errors

Example

curl -X DELETE "https://api.ibel.ai/v1/auth/passkeys/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $SESSION"

Rename a passkey#

Parameters

• idstring (uuid)pathrequired

Request bodyapplication/json

• namestringrequired

  1–60 characters

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/auth/passkeys/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"name":"my-api"}'

Start a passkey sign-in#

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/passkeys/signin/options"

Sign in with a passkey#

The session starts stepped up (a passkey is user-verified).

Request bodyapplication/json

• challenge_idstring (uuid)required
• credentialobjectrequired

  what PublicKeyCredential.toJSON() returns: id, rawId, type, response

• teamstring (uuid)

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/passkeys/signin/verify" \
  -d '{"challenge_id":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","credential":{}}'

Start a step-up with a passkey#

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/step-up/passkey/options" \
  -H "Authorization: Bearer $SESSION"

Confirm a step-up with a passkey#

Request bodyapplication/json

• challenge_idstring (uuid)required
• credentialobjectrequired

  what PublicKeyCredential.toJSON() returns: id, rawId, type, response

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/step-up/passkey/verify" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"challenge_id":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","credential":{}}'

Start adding an authenticator app#

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/totp/setup" \
  -H "Authorization: Bearer $SESSION"

Turn the authenticator app on#

Request bodyapplication/json

• codestringrequired

  pattern ^\d{6}$

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/totp/confirm" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"code":"123456"}'

Remove the authenticator app#

Response

Errors

Example

curl -X DELETE "https://api.ibel.ai/v1/auth/totp" \
  -H "Authorization: Bearer $SESSION"

Start a device login (CLI)#

Request bodyapplication/json

• namestring

  up to 80 characters

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/device" \
  -d '{"name":"my-api"}'

Approve or deny a device code#

Step-up is needed to approve, not to deny.

Request bodyapplication/json

• user_codestringrequired
• denyboolean

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/device/approve" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"user_code":"WDJB-MJHT"}'

Poll for the device's API key#

RFC 8628: every polling error is a 400, authorization_pending included.

Request bodyapplication/json

• device_codestringrequired

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/auth/device/token" \
  -d '{"device_code":"…"}'