Sign-in and sessions


POST	`/api/auth/login`
POST	`/api/auth/login-options`
POST	`/api/auth/mfa/verify`
POST	`/api/auth/mfa/send-otp`
POST	`/api/auth/refresh`
POST	`/api/auth/logout`
GET	`/api/auth/me`
DELETE	`/api/auth/identities/:id`
POST	`/api/auth/password/set/send-code`
POST	`/api/auth/password/set`
GET	`/api/auth/sessions`
DELETE	`/api/auth/sessions/:id`
POST	`/api/auth/sessions/revoke-others`
GET	`/api/auth/invite/:token`
POST	`/api/auth/invite/:token/accept`
GET	`/api/auth/password-reset/:token`
POST	`/api/auth/password-reset/:token/reset`
POST	`/api/auth/password-reset`
GET	`/api/auth/registration-status`
POST	`/api/auth/register`
POST	`/api/auth/verify-email/:token`

POST/api/auth/login

Existing routes.

Authentication: none.
Rate limit: 10 requests per minute per IP address.

Request body

Name	Type	Required	Notes
`email`	string	Yes	An email address.
`password`	string	Yes	At least 1 characters.

bash

curl -X POST "https://shellius.example.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "…",
    "password": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

POST/api/auth/login-options

Authentication: none.
Rate limit: 10 requests per minute per IP address.

Request body

Name	Type	Required	Notes
`email`	string	Yes	An email address.

bash

curl -X POST "https://shellius.example.com/api/auth/login-options" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

Complete MFA challenge

POST/api/auth/mfa/verify

Authentication: none.
Rate limit: 10 requests per minute per IP address.

Request body

Name	Type	Required	Notes
`mfaToken`	string	Yes
`method`	string	Yes	One of `totp`, `email`, `backup`.
`code`	string	Yes

bash

curl -X POST "https://shellius.example.com/api/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "mfaToken": "…",
    "method": "totp",
    "code": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

Email OTP during MFA challenge

POST/api/auth/mfa/send-otp

Authentication: none.
Rate limit: 10 requests per minute per IP address.

Request body

Name	Type	Required	Notes
`mfaToken`	string	Yes

bash

curl -X POST "https://shellius.example.com/api/auth/mfa/send-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "mfaToken": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

Rotate refresh token

POST/api/auth/refresh

Authentication: none.
Rate limit: 10 requests per minute per IP address.

Request body

Name	Type	Required	Notes
`refreshToken`	string	Yes

bash

curl -X POST "https://shellius.example.com/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

Revoke refresh token

POST/api/auth/logout

Authentication: bearer token.
Permission: any signed-in user.

Request body

Name	Type	Required	Notes
`refreshToken`	string	Yes

bash

curl -X POST "https://shellius.example.com/api/auth/logout" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "…"
  }'

204 No Content on success.

Caller profile + SSO identities

GET/api/auth/me

Authentication: bearer token.
Permission: any signed-in user.

bash

curl -X GET "https://shellius.example.com/api/auth/me" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

json

{ "success": true, "data": { … } }

Unlink own SSO identity

DELETE/api/auth/identities/:id

Unlink one of the caller's SSO identities.

Authentication: bearer token.
Permission: any signed-in user.

Path parameters

Name	Type	Notes
`id`	string

bash

curl -X DELETE "https://shellius.example.com/api/auth/identities/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

204 No Content on success.

Password set send code

POST/api/auth/password/set/send-code

Authentication: bearer token.
Permission: any signed-in user.

bash

curl -X POST "https://shellius.example.com/api/auth/password/set/send-code" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

json

{ "success": true, "data": { … } }

Password set

POST/api/auth/password/set

Authentication: bearer token.
Permission: any signed-in user.

Request body

Name	Type	Required	Notes
`newPassword`	object	No
`method`	string	Yes	One of `totp`, `email`, `backup`.
`code`	string	Yes	1–64 characters.

bash

curl -X POST "https://shellius.example.com/api/auth/password/set" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "totp",
    "code": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

List own refresh-token families

GET/api/auth/sessions

Sessions — self-service listing/revocation of refresh-token families.

Authentication: bearer token.
Permission: any signed-in user.

bash

curl -X GET "https://shellius.example.com/api/auth/sessions" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

json

{ "success": true, "data": { … } }

Revoke one own session family

DELETE/api/auth/sessions/:id

Authentication: bearer token.
Permission: any signed-in user.

Path parameters

Name	Type	Notes
`id`	string

bash

curl -X DELETE "https://shellius.example.com/api/auth/sessions/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

204 No Content on success.

Revoke all other own sessions

POST/api/auth/sessions/revoke-others

Authentication: bearer token.
Permission: any signed-in user.

bash

curl -X POST "https://shellius.example.com/api/auth/sessions/revoke-others" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

json

{ "success": true, "data": { … } }

Peek invite token

GET/api/auth/invite/:token

Public; peek at token without consuming.

Authentication: none — the token in the request is the credential.

Path parameters

Name	Type	Notes
`token`	string

bash

curl -X GET "https://shellius.example.com/api/auth/invite/{token}"

200 OK

json

{ "success": true, "data": { … } }

Accept invite: set password, status=active, log in

POST/api/auth/invite/:token/accept

Public; consume token, set password, log in.

Authentication: none — the token in the request is the credential.
Rate limit: 5 requests per 15 minutes per IP address.

Path parameters

Name	Type	Notes
`token`	string

Request body

Name	Type	Required	Notes
`password`	object	No

bash

curl -X POST "https://shellius.example.com/api/auth/invite/{token}/accept" \
  -H "Content-Type: application/json" \
  -d '{
    "password": {}
  }'

200 OK

json

{ "success": true, "data": { … } }

Peek reset token

GET/api/auth/password-reset/:token

Public; peek at token without consuming.

Authentication: none — the token in the request is the credential.

Path parameters

Name	Type	Notes
`token`	string

bash

curl -X GET "https://shellius.example.com/api/auth/password-reset/{token}"

200 OK

json

{ "success": true, "data": { … } }

Consume reset token, set password, log in

POST/api/auth/password-reset/:token/reset

Public; consume token, set new password.

Authentication: none — the token in the request is the credential.
Rate limit: 5 requests per 15 minutes per IP address.

Path parameters

Name	Type	Notes
`token`	string

Request body

Name	Type	Required	Notes
`password`	object	No

bash

curl -X POST "https://shellius.example.com/api/auth/password-reset/{token}/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "password": {}
  }'

200 OK

json

{ "success": true, "data": { … } }

Self-service reset request

POST/api/auth/password-reset

Public self-service; ALWAYS returns 204 (no enum)

Authentication: none.
Rate limit: 5 requests per 15 minutes per IP address.

Request body

Name	Type	Required	Notes
`email`	string	Yes	An email address.

bash

curl -X POST "https://shellius.example.com/api/auth/password-reset" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "…"
  }'

204 No Content on success.

Is self-registration enabled

GET/api/auth/registration-status

Public; returns { enabled: bool }.

Authentication: none.

bash

curl -X GET "https://shellius.example.com/api/auth/registration-status"

200 OK

json

{ "success": true, "data": { … } }

Self-service registration

POST/api/auth/register

Public self-service registration.

Authentication: none.
Rate limit: 5 requests per 15 minutes per IP address.

Request body

Name	Type	Required	Notes
`email`	string	Yes	An email address.
`name`	string	Yes	1–120 characters.
`password`	object	No

bash

curl -X POST "https://shellius.example.com/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "…",
    "name": "…"
  }'

200 OK

json

{ "success": true, "data": { … } }

Verify email -> status active

POST/api/auth/verify-email/:token

Public; consume token, flip status to active.

Authentication: none — the token in the request is the credential.
Rate limit: 5 requests per 15 minutes per IP address.

Path parameters

Name	Type	Notes
`token`	string

bash

curl -X POST "https://shellius.example.com/api/auth/verify-email/{token}"

200 OK

json

{ "success": true, "data": { … } }

Password login ​

Email-first login options ​

Complete MFA challenge ​

Email OTP during MFA challenge ​

Rotate refresh token ​

Revoke refresh token ​

Caller profile + SSO identities ​

Unlink own SSO identity ​

Password set send code ​

Password set ​

List own refresh-token families ​

Revoke one own session family ​

Revoke all other own sessions ​

Peek invite token ​

Accept invite: set password, status=active, log in ​

Peek reset token ​

Consume reset token, set password, log in ​

Self-service reset request ​

Is self-registration enabled ​

Self-service registration ​

Verify email -> status active ​

Password login

Email-first login options

Complete MFA challenge

Email OTP during MFA challenge

Rotate refresh token

Revoke refresh token

Caller profile + SSO identities

Unlink own SSO identity

Password set send code

Password set

List own refresh-token families

Revoke one own session family

Revoke all other own sessions

Peek invite token

Accept invite: set password, status=active, log in

Peek reset token

Consume reset token, set password, log in

Self-service reset request

Is self-registration enabled

Self-service registration

Verify email -> status active