Authentication¶

Althost is an authentication provider for your applications. Your users sign in on auth.althost.dev. Althost issues JSON Web Tokens (JWT) for your application. Your application validates these tokens to identify users.

Althost issues the tokens. Althost never passes a token from an external provider to your application. Google or another provider only confirms the user's identity inside the Althost service.

Your application sends the user to the login page.
The user signs in with email and password, an email link, a one-time code, or Google.
Althost verifies the user and issues tokens.
Althost redirects the browser back to your application with the tokens in the URL fragment.

The login page address is:

https://auth.althost.dev/auth/project/<projectId>/login

You can copy this link from the Auth page in the portal. The portal shows the full link, so you do not need to find the project ID yourself. To build the link manually, use the project ID from the portal. Add a returnUrl parameter to send the user back to a specific page:

https://auth.althost.dev/auth/project/<projectId>/login?returnUrl=https://your-app.example/callback

The returnUrl value overrides the configured redirect URL for that sign-in. It must match one of the approved return URLs exactly. See Return URLs.

Token handoff¶

After a successful sign-in, Althost redirects to the redirect URL with the tokens in the URL fragment:

https://your-app.example/callback#access_token=<jwt>&refresh_token=<jwt>

The browser does not send the URL fragment to the server. Your application's frontend reads the fragment and stores the tokens. Your frontend sends the access token to your backend as a bearer token.

Configure authentication¶

Open the Auth page in the portal for your project. Enable authentication and select the sign-in methods.

Method	Value	How it works
Email + Password	`email_password`	The user enters an email and a password.
Email Link	`email_link`	The user requests a link by email. The link signs them in.
Email OTP	`email_otp`	The user requests a one-time code by email.
Google	`google`	The user signs in with their Google account.

Allowed domains¶

The JWT aud claim contains the allowed domains. Your application must check that its domain is in aud. This prevents a token from one project being accepted by another.

Return URLs¶

Set the URL where users go after a successful sign-in. This is the default destination. Althost uses it when the caller sends no returnUrl.

Set the approved return URLs in the Auth page. These are the destinations your applications are allowed to use. A returnUrl parameter must match one of the approved return URLs exactly (byte for byte). The comparison is case-sensitive and includes the full URL, the scheme, and any path, query, or fragment. Althost rejects a returnUrl that does not match an approved entry. This prevents open redirects.

Add one entry per line. Include each exact URL your applications use. For example:

https://your-app.example/callback
https://admin.example.com/callback
myapp://auth-callback

The list accepts web URLs and app URIs.

Without a matching returnUrl and without a default redirect URL, Althost sends the user to the first allowed domain.

Allowed CORS origins¶

Set the origins that may call the auth API from the browser. This is separate from the allowed domains.

Althost checks the Origin header of each request. A request from an origin that is not approved gets a 403 response. The auth portal origin is always allowed. A request without an Origin header (for example a server-to-server call from your backend) is always allowed.

Add the full origin, including the scheme. For example https://app.example.com. Do not add app URIs here. App URIs belong in the approved return URLs.

Branding¶

Upload a logo, banner, and favicon on the Assets page. The sign-in pages show the banner as a background and the logo in the sign-in card. They also show the project name. Without images, the sign-in pages use the Althost blueprint background.

Registration and email verification¶

Turn registration on or off per project. When registration is on, the sign-in page shows a link to create an account. You can require email verification. Althost sends the verification link by email.

Validate tokens¶

Your backend validates an access token by calling the verify endpoint:

POST /auth/project/<projectId>/verify
Authorization: Bearer <access_token>

The response on success:

{
  "valid": true,
  "user": { "id": "...", "email": "...", "name": "..." }
}

The response on failure:

{
  "error": "Invalid token",
  "authUrl": "https://auth.althost.dev/auth/project/<projectId>/login"
}

Refresh tokens¶

Access tokens expire. The default lifetime is 24 hours. When the access token expires, your backend calls the refresh endpoint with the refresh token:

POST /auth/project/<projectId>/refresh
Content-Type: application/json

{
  "refreshToken": "<jwt>"
}

The response on success:

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>"
}

The response on failure:

{
  "error": "Invalid or expired token",
  "authUrl": "https://auth.althost.dev/auth/project/<projectId>/login"
}

Refresh token rotation¶

Althost rotates the refresh token on each use. The old token is invalid after use. Althost issues a new token pair each time. If a used refresh token is presented again, Althost rejects it.

When refresh fails¶

Redirect the user to authUrl. The user signs in again. After the sign-in, the user returns to your application.

Custom authentication pages¶

You can build your own registration and authentication pages. Your pages call the Althost auth API. The API creates users and authenticates them.

Authenticate each API call with an API key that has the auth scopes. See API keys and scopes. Keep the API key on your backend. Do not put the API key in a browser.

The API endpoints:

Method	Path	Scope	Purpose
POST	`/auth/project/<projectId>/users`	`auth:users:create`	Create a user
POST	`/auth/project/<projectId>/authenticate`	`auth:users:authenticate`	Sign in a user and get tokens
GET	`/auth/project/<projectId>/users/<userId>`	`auth:users:read`	Get a user
DELETE	`/auth/project/<projectId>/users/<userId>`	`auth:users:delete`	Delete a user account

Create a user¶

POST /auth/project/<projectId>/users
Authorization: Bearer ak_xxx
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret",
  "name": "Jane"
}

The response on success is 201 with the created user. The response is 409 if the email is already registered. When the project requires email verification, Althost sends a verification email.

Authenticate a user¶

POST /auth/project/<projectId>/authenticate
Authorization: Bearer ak_xxx
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret"
}

The response on success:

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>",
  "user": { "id": "...", "email": "user@example.com", "name": "Jane" }
}

Your page receives the tokens. Use them in the same way as the hosted sign-in flow. If your page runs in a browser, its origin must be in the approved CORS origins.

Account deletion¶

Users can delete their accounts. Althost deletes the platform user and all of their auth data.

For a user who signed in with an external provider, Althost also requests deletion of the user's identity at the provider. Both deletions run as one transaction. If the provider deletion fails, Althost cancels the whole deletion. The user stays active in both systems. The user can try again.

Althost stores the external provider identity on the user record. Althost uses it to delete the identity at the provider. For a Google user, Althost deletes the app's identity account. It does not delete the user's Google account itself. The user deletes that through Google.

Delete page¶

The app sends the signed-in user to the delete page:

https://auth.althost.dev/auth/project/<projectId>/delete-account#access_token=<jwt>

The page shows the signed-in user and a confirmation button. The user confirms, and the account is deleted.

Delete via API¶

Your backend can delete a user with an API key:

DELETE /auth/project/<projectId>/users/<userId>
Authorization: Bearer ak_xxx

A signed-in user can delete their own account with their access token:

DELETE /auth/project/<projectId>/me
Authorization: Bearer <access_token>

API keys and scopes¶

Create an API key in the portal under Settings → API Keys. Grant the auth scopes your integration needs:

Scope	Grants
`auth:users:create`	Create users
`auth:users:authenticate`	Authenticate users
`auth:users:read`	Read user details
`auth:users:delete`	Delete user accounts

Send the API key as a bearer token or an x-api-key header. The key works only for projects in the same account as the key.

JWT reference¶

Claim	Description
`iss`	Always `althost`
`sub`	The user's platform ID
`email`	The user's email address
`aud`	The allowed domains from the auth config
`projectId`	The project the token was issued for
`tokenType`	`access` or `refresh`
`iat`	Issue time
`exp`	Expiry time

Token storage¶

Web applications: use an httpOnly, secure cookie.
Single-page applications: keep tokens in memory.
Do not store tokens in localStorage. It is vulnerable to XSS.

Invalidate all sessions¶

The project owner can invalidate all tokens from the Auth page. Althost deletes every refresh token for the project. Users must sign in again. Access tokens keep working until they expire.

Authentication¶

The sign-in flow¶

Token handoff¶

Configure authentication¶

Sign-in methods¶

Allowed domains¶

Return URLs¶

Allowed CORS origins¶

Branding¶

Registration and email verification¶

Validate tokens¶

Refresh tokens¶

Refresh token rotation¶

When refresh fails¶

Custom authentication pages¶

Create a user¶

Authenticate a user¶

Account deletion¶

Delete page¶

Delete via API¶

API keys and scopes¶

JWT reference¶

Token storage¶

Invalidate all sessions¶