Skip to content
OpenSmartRoute
Documentation
Hosted platformREST API reference

Sign-in and sessions

Sign-in with GitHub, Google or an organization identity provider; browser sessions; and CLI sign-in with device codes (`osr login`): the CLI requests a code, the person approves it in the browser, the CLI receives a workspace API key.

API version 1.0.0openapi.json

Sign-in with GitHub, Google or an organization identity provider; browser sessions; and CLI sign-in with device codes (`osr login`): the CLI requests a code, the person approves it in the browser, the CLI receives a workspace API key.

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.

Request bodyDeviceDecisionIn

FieldTypeDefaultDescription
namestring""
user_code(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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" }'
Bodyjson
{
  "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.

Request bodyDeviceCodeIn

FieldTypeDefaultDescription
client_namestring""

Responses

201Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/device/code" \
  -H "Content-Type: application/json" \
  -d '{}'
Bodyjson
{}

post/api/v1/auth/device/deny

Device Deny

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

Requires an API key.

Request bodyDeviceDecisionIn

FieldTypeDefaultDescription
namestring""
user_code(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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" }'
Bodyjson
{
  "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.

Request bodyDeviceTokenIn

FieldTypeDefaultDescription
device_code(required)string
grant_typestring"urn:ietf:params:oauth:grant-type:device_code"

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/device/token" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "string" }'
Bodyjson
{
  "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.

Parameters

NameInTypeDefaultDescription
user_code(required)pathstring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
email(required)querystring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s "$OSR_URL/api/v1/auth/discover"

get/api/v1/auth/identities

Identities

Requires an API key.

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
provider(required)pathstring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
token(required)pathstring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s "$OSR_URL/api/v1/auth/invites/<token>"

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

Invite Accept

Requires an API key.

Parameters

NameInTypeDefaultDescription
token(required)pathstring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
everywherequerybooleanfalse

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/logout?everywhere=false" \
  -H "Authorization: Bearer $OSR_API_KEY"

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.

Request bodyPasswordChangeIn

FieldTypeDefaultDescription
current_passwordstring | null
password(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/password" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "string" }'
Bodyjson
{
  "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.

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Request bodyForgotPasswordIn

FieldTypeDefaultDescription
email(required)string

Responses

202Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'
Bodyjson
{
  "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.

No authentication.

Request bodyPasswordLoginIn

FieldTypeDefaultDescription
email(required)string
password(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/password/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "password": "string" }'
Bodyjson
{
  "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.

No authentication.

Request bodyResetPasswordIn

FieldTypeDefaultDescription
password(required)string
token(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{ "password": "string", "token": "string" }'
Bodyjson
{
  "password": "string",
  "token": "string"
}

get/api/v1/auth/providers

Providers

No authentication.

Responses

200Successful Response
Requestbash
curl -s "$OSR_URL/api/v1/auth/providers"

get/api/v1/auth/sessions

Sessions

Requires an API key.

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
session_id(required)pathstring

Responses

200Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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).

No authentication.

Request bodyVerifyEmailIn

FieldTypeDefaultDescription
token(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{ "token": "string" }'
Bodyjson
{
  "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.

Responses

202Successful Response
422Validation ErrorHTTPValidationError
401Missing, invalid or revoked API key
Requestbash
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.

Parameters

NameInTypeDefaultDescription
provider(required)pathstring

Request bodySsoCallbackIn

FieldTypeDefaultDescription
code(required)string
state(required)string

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s -X POST "$OSR_URL/api/v1/auth/<provider>/callback" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string", "state": "string" }'
Bodyjson
{
  "code": "string",
  "state": "string"
}

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

Start

No authentication.

Parameters

NameInTypeDefaultDescription
provider(required)pathstring
nextquerystring | null

Responses

200Successful Response
422Validation ErrorHTTPValidationError
Requestbash
curl -s "$OSR_URL/api/v1/auth/<provider>/start"

Workspaces

Organization workspaces: members, roles, invitations and organization SSO (browser sessions only).

Billing

Plan upgrades through Stripe Checkout and the webhook that confirms them.

On this page

POST /api/v1/auth/device/approvePOST /api/v1/auth/device/codePOST /api/v1/auth/device/denyPOST /api/v1/auth/device/tokenGET /api/v1/auth/device/{user_code}GET /api/v1/auth/discoverGET /api/v1/auth/identitiesDELETE /api/v1/auth/identities/{provider}GET /api/v1/auth/invites/{token}POST /api/v1/auth/invites/{token}/acceptPOST /api/v1/auth/logoutPOST /api/v1/auth/passwordDELETE /api/v1/auth/passwordPOST /api/v1/auth/password/forgotPOST /api/v1/auth/password/loginPOST /api/v1/auth/password/resetGET /api/v1/auth/providersGET /api/v1/auth/sessionsDELETE /api/v1/auth/sessions/{session_id}POST /api/v1/auth/verifyPOST /api/v1/auth/verify/sendPOST /api/v1/auth/{provider}/callbackGET /api/v1/auth/{provider}/start