Sign-in and sessions

post/api/v1/auth/device/approve

Device Approve

Approve a CLI sign-in for the caller's current workspace (admin role; counts against the plan's keys).

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/device/approve" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_code": "string" }'

{
  "user_code": "string"
}

post/api/v1/auth/device/code

Device Code

Start a CLI sign-in: returns a secret device_code for polling and a short user_code to approve. The CLI opens verification_uri_complete in a browser; the signed-in person approves the code there and the CLI receives a workspace API key from /device/token. Anonymous; limited per client.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/device/code" \
  -H "Content-Type: application/json" \
  -d '{}'

{}

post/api/v1/auth/device/deny

Device Deny

Refuse a CLI sign-in; the polling CLI receives access_denied.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/device/deny" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_code": "string" }'

{
  "user_code": "string"
}

post/api/v1/auth/device/token

Device Token

Poll for the outcome of a CLI sign-in (RFC 8628 section 3.4/3.5). 200 with access_token (a new workspace API key, shown once) once approved; otherwise 400 with error = authorization_pending, slow_down (poll less often), access_denied or expired_token. Each device code can be exchanged once.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/device/token" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "string" }'

{
  "device_code": "string"
}

get/api/v1/auth/device/{user_code}

Device Info

What the browser shows before approving: the client name, when the code expires and its status.

Requires an API key

curl -s "$OSR_URL/api/v1/auth/device/<user_code>" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/auth/discover

Discover

Sign-in options for an email: the shared providers plus the organization's own IdP, if any. Never reveals whether the address has an account.

No authentication

curl -s "$OSR_URL/api/v1/auth/discover"

post/api/v1/auth/email

Email Change

Ask to move the signed-in user's account to a new address: a confirmation goes to that address and the change happens when its link is opened (POST /api/v1/auth/verify). The current password is required when one is set; a session is required (a key cannot change the person's address).

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/email" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'

{
  "email": "ada@example.com"
}

get/api/v1/auth/identities

Identities

Requires an API key

curl -s "$OSR_URL/api/v1/auth/identities" \
  -H "Authorization: Bearer $OSR_API_KEY"

delete/api/v1/auth/identities/{provider}

Unlink

Requires an API key

curl -s -X DELETE "$OSR_URL/api/v1/auth/identities/<provider>" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/auth/invites/{token}

Invite Info

No authentication

curl -s "$OSR_URL/api/v1/auth/invites/<token>"

post/api/v1/auth/invites/{token}/accept

Invite Accept

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/invites/<token>/accept" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/auth/logout

Logout

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/logout?everywhere=false" \
  -H "Authorization: Bearer $OSR_API_KEY"

delete/api/v1/auth/mfa

Mfa Disable

Switch the second factor off for the signed-in user (password and a current code - or an unused recovery code - required); a security notice is sent.

Requires an API key

curl -s -X DELETE "$OSR_URL/api/v1/auth/mfa" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string", "current_password": "string" }'

{
  "code": "string",
  "current_password": "string"
}

post/api/v1/auth/mfa/enable

Mfa Enable

Confirm the pending secret with a code from the app; returns the recovery codes - shown once. Other browsers are signed out and a security notice is sent.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/mfa/enable" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string" }'

{
  "code": "string"
}

post/api/v1/auth/mfa/recovery-codes

Mfa Recovery Codes

Replace the recovery codes (a current authenticator code confirms it); the old ones stop working.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/mfa/recovery-codes" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string" }'

{
  "code": "string"
}

post/api/v1/auth/mfa/setup

Mfa Setup

Start enrolling an authenticator app: a fresh TOTP secret (pending until /mfa/enable confirms a code) with the otpauth:// URI. Needs a password on the account - the factor guards password sign-in; identity providers bring their own. Re-running replaces a pending secret.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/mfa/setup" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "current_password": "string" }'

{
  "current_password": "string"
}

post/api/v1/auth/mfa/verify

Mfa Verify

Second step of a password sign-in: the challenge from /password/login (or /password/reset) plus a six-digit authenticator code or an unused recovery code (each works once) buys the session.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{ "challenge": "string", "code": "string" }'

{
  "challenge": "string",
  "code": "string"
}

post/api/v1/auth/password

Password Set

Set or change the signed-in user's password (the current one is required once set).

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/password" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "string" }'

{
  "password": "string"
}

delete/api/v1/auth/password

Password Remove

Remove password sign-in; refused when it is the only way into the account.

Requires an API key

curl -s -X DELETE "$OSR_URL/api/v1/auth/password" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/auth/password/forgot

Password Forgot

Email a single-use password-reset link. Always 202 so the response never reveals whether an address has an account; the link expires after one hour.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'

{
  "email": "ada@example.com"
}

post/api/v1/auth/password/login

Password Login

Sign in with email and password; returns a browser session like the SSO callback does - or, when the account has two-factor authentication, mfa_required with a five-minute challenge to redeem at POST /auth/mfa/verify with the authenticator (or a recovery) code.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/password/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "password": "string" }'

{
  "email": "ada@example.com",
  "password": "string"
}

post/api/v1/auth/password/reset

Password Reset

Set a new password with the emailed token; proves the inbox, so the address becomes verified. Every existing session of the user is revoked and a fresh one is returned - unless the account has two-factor authentication: then mfa_required with a challenge for /auth/mfa/verify comes back, since the inbox alone is not the second factor.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{ "password": "string", "token": "string" }'

{
  "password": "string",
  "token": "string"
}

get/api/v1/auth/providers

Providers

No authentication

curl -s "$OSR_URL/api/v1/auth/providers"

get/api/v1/auth/sessions

Sessions

Requires an API key

curl -s "$OSR_URL/api/v1/auth/sessions" \
  -H "Authorization: Bearer $OSR_API_KEY"

delete/api/v1/auth/sessions/{session_id}

Revoke Session

Requires an API key

curl -s -X DELETE "$OSR_URL/api/v1/auth/sessions/<session_id>" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/auth/verify

Verify

Confirm an email address with the token from the message (works signed out). The same link confirms a new address asked for with POST /api/v1/auth/email: the account moves to it.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{ "token": "string" }'

{
  "token": "string"
}

post/api/v1/auth/verify/send

Verify Send

Re-send the address confirmation email to the signed-in user (at most once a minute).

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/auth/verify/send" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/auth/{provider}/callback

Callback

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/<provider>/callback" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string", "state": "string" }'

{
  "code": "string",
  "state": "string"
}

post/api/v1/auth/{provider}/credential

Credential

Sign in with an ID token the browser obtained itself - Google's One Tap prompt. The provider validates the token (audience, issuer, expiry); the answer is the same browser session as /callback. Limited per client because it needs no server-issued state.

No authentication

curl -s -X POST "$OSR_URL/api/v1/auth/<provider>/credential" \
  -H "Content-Type: application/json" \
  -d '{ "credential": "string" }'

{
  "credential": "string"
}

get/api/v1/auth/{provider}/start

Start

No authentication

curl -s "$OSR_URL/api/v1/auth/<provider>/start"