Signing in & access tokens

Most of the time you never think about this: you sign in once in the browser and stay signed in. This page matters when something other than a browser has to reach your machine.

In the browser

Sign in at the Hoshi sign-in page and you are done — the session is held in a cookie and carried for you. Where an organization uses single sign-on, use the SSO button instead of a password: you are sent to the identity provider and back.

From a CLI, a script, or the desktop app

Anything that is not a browser authenticates with a personal access token. Open Settings → CLI tokens, create a token and give it a name you will recognize later, then copy it immediately — the value is shown once and cannot be retrieved afterwards. Send it as a bearer token on each request.

curl -H "Authorization: Bearer hoshi_your_token_here" \
  https://your-machine-address/sessions

A token carries your identity, so treat it like a password. If one leaks, delete it from the same screen: revoking takes effect immediately, and anything using it stops working at once. The desktop app and the terminal client both use a token behind the scenes — you sign in once and they store it for you.

Single sign-on

Hoshi supports signing in through an OIDC identity provider, matched on your email domain: where a connection exists for the domain in your address, the sign-in page offers SSO instead of a password. Connections are configured by whoever operates the instance rather than from the app — there is no self-service SSO screen yet. An operator sets one up with environment variables on the platform API.

SSO_ISSUER=https://your-provider.example.com
SSO_CLIENT_ID=...
SSO_CLIENT_SECRET=...
SSO_EMAIL_DOMAIN=yourcompany.com
SSO_ORG_ID=            # optional

SSO_ORG_ID is optional: setting it puts everyone who signs in through that provider straight into one organization.

Revoking access

• A token — delete it in Settings → CLI tokens.
• A browser session — sign out, or end other active sessions from Settings → Security.
• A person — remove them from the organization in Manage → Members, and their access to its machines goes with it.