Every authenticated call carries a bearer token:

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

The token is a short-lived JWT. On each request Shellius re-loads the user, so a deactivated account, a "sign out everywhere", or a role change takes effect on the very next call rather than when the token expires.

Token	Default lifetime	Setting
Access token	15 minutes	JWT_EXPIRY
Refresh token	7 days	JWT_REFRESH_EXPIRY

Sign in with a password

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

{
  "success": true,
  "data": {
    "accessToken": "eyJ…",
    "refreshToken": "eyJ…",
    "user": { }
  }
}

If the account has a second factor

When the user has any second factor enrolled, login does not return tokens. It returns a challenge instead:

{
  "success": true,
  "data": {
    "mfaRequired": true,
    "mfaToken": "…",
    "methods": ["totp", "backup"],
    "emailHint": "a•••@example.com"
  }
}

Complete it with POST /api/auth/mfa/verify, sending the mfaToken, a method of totp, email or backup, and the code. That call returns the tokens. For the email method, request a code first with POST /api/auth/mfa/send-otp.

Automation accounts

A script cannot answer a TOTP prompt unless you give it the TOTP secret. If your organisation enforces two-factor authentication, that is the honest trade-off until Shellius has service tokens: either the automation user holds a TOTP secret in your secret manager, or the task stays manual.

If the organisation requires single sign-on

Password sign-in is refused with 403 SSO_REQUIRED for everyone except users whose role holds settings.sso. SSO is a browser redirect flow and is not usable from a script.

Refresh

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

The response contains a new accessToken and a new refreshToken. Refresh tokens rotate: store the new one and discard the old one each time.

Sign out

POST /api/auth/logout with the refreshToken in the body revokes it and returns 204. To list or revoke your other sessions, see Sign-in and sessions.

The device flow, for CLIs

The shellius terminal client never sees a password. It uses the OAuth 2.0 device authorization flow (RFC 8628):

Polling is limited to 30 requests per minute per IP address. See Device authorization.

Calls that are not made by users

Two groups of endpoints authenticate differently, and you will normally never call them yourself:

• Host agent endpoints under /api/hosts are called by managed hosts, using the agent token installed at bootstrap.
• Bootstrap script endpoints are fetched with curl on the host, and the one-time token in the URL is the credential.

Next steps

QuickstartPut it together: sign in, list servers, request access.ErrorsWhat a refusal looks like.