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.0

post	/api/v1/auth/device/approve	Device Approve
post	/api/v1/auth/device/code	Device Code
post	/api/v1/auth/device/deny	Device Deny
post	/api/v1/auth/device/token	Device Token
get	/api/v1/auth/device/{user_code}	Device Info
get	/api/v1/auth/discover	Discover
get	/api/v1/auth/identities	Identities
delete	/api/v1/auth/identities/{provider}	Unlink
get	/api/v1/auth/invites/{token}	Invite Info
post	/api/v1/auth/invites/{token}/accept	Invite Accept
post	/api/v1/auth/logout	Logout
post	/api/v1/auth/password	Password Set
delete	/api/v1/auth/password	Password Remove
post	/api/v1/auth/password/forgot	Password Forgot
post	/api/v1/auth/password/login	Password Login
post	/api/v1/auth/password/reset	Password Reset
get	/api/v1/auth/providers	Providers
get	/api/v1/auth/sessions	Sessions
delete	/api/v1/auth/sessions/{session_id}	Revoke Session
post	/api/v1/auth/verify	Verify
post	/api/v1/auth/verify/send	Verify Send
post	/api/v1/auth/{provider}/callback	Callback
get	/api/v1/auth/{provider}/start	Start

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

Field	Type	Default	Description
name	string	""
user_code(required)	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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_codeto approve. The CLI opensverification_uri_completein 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

Field	Type	Default	Description
client_name	string	""

Responses

201	Successful Response
422	Validation 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

Field	Type	Default	Description
name	string	""
user_code(required)	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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 400witherror = authorization_pending, slow_down (poll less often), access_deniedorexpired_token`. Each device code can be exchanged once.

No authentication.

Request bodyDeviceTokenIn

Field	Type	Default	Description
device_code(required)	string
grant_type	string	"urn:ietf:params:oauth:grant-type:device_code"

Responses

200	Successful Response
422	Validation 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

Name	In	Type	Default	Description
user_code(required)	path	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
email(required)	query	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError

Requestbash

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

get/api/v1/auth/identities

Identities

Requires an API key.

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
provider(required)	path	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
token(required)	path	string

Responses

200	Successful Response
422	Validation 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

Name	In	Type	Default	Description
token(required)	path	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
everywhere	query	boolean	false

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Field	Type	Default	Description
current_password	string \| null
password(required)	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Field	Type	Default	Description
email(required)	string

Responses

202	Successful Response
422	Validation 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

No authentication.

Request bodyPasswordLoginIn

Field	Type	Default	Description
email(required)	string
password(required)	string

Responses

200	Successful Response
422	Validation 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

Field	Type	Default	Description
password(required)	string
token(required)	string

Responses

200	Successful Response
422	Validation 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

200	Successful Response

Requestbash

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

get/api/v1/auth/sessions

Sessions

Requires an API key.

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
session_id(required)	path	string

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Field	Type	Default	Description
token(required)	string

Responses

200	Successful Response
422	Validation 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

202	Successful Response
422	Validation ErrorHTTPValidationError
401	Missing, 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

Name	In	Type	Default	Description
provider(required)	path	string

Request bodySsoCallbackIn

Field	Type	Default	Description
code(required)	string
state(required)	string

Responses

200	Successful Response
422	Validation 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

Name	In	Type	Default	Description
provider(required)	path	string
next	query	string \| null

Responses

200	Successful Response
422	Validation ErrorHTTPValidationError

Requestbash

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