# Sign in with Voozin

Voozin is an OAuth 2.1 and OpenID Connect provider. Websites and apps can let people sign in with their Voozin account, and mail apps can connect to a mailbox over IMAP, SMTP and CalDAV without an app password. Every app asks for consent, and people can disconnect it at any time.

## Register an app

1. In the dashboard open **Developers → Developer apps** and click **Create app**. You need a role that can manage developer settings, the same as for API keys and webhooks.
2. Choose the type:
   - **Website**: your server keeps a client secret. Redirect URIs use `https` (`http://localhost` works for development).
   - **App**: desktop and mobile apps that can't keep a secret, so they sign in with PKCE alone. Redirect URIs are loopback addresses such as `http://127.0.0.1/callback` (any port is accepted at sign-in) or a private-use scheme such as `com.example.app:/oauth`.
3. Tick **Mail and calendar access** if the app needs IMAP, SMTP or CalDAV.
4. Optionally add **Sign-out redirect URIs**: the pages people may return to after signing out of your app (see [Signing out](#signing-out)). They follow the same rules as redirect URIs.
5. Copy the client ID, and for websites the client secret. The secret is shown once; rotate it from the same page if it leaks.

The name and homepage you enter are shown on the consent screen.

## Endpoints

The issuer is `https://auth.voozin.com`. Libraries that support discovery only need the issuer.

| Endpoint | URL |
| --- | --- |
| Discovery | `https://auth.voozin.com/.well-known/openid-configuration` |
| Authorization | `https://auth.voozin.com/api/auth/oauth2/authorize` |
| Token | `https://auth.voozin.com/api/auth/oauth2/token` |
| User info | `https://auth.voozin.com/api/auth/oauth2/userinfo` |
| Keys (JWKS) | `https://auth.voozin.com/api/auth/jwks` |
| Revocation | `https://auth.voozin.com/api/auth/oauth2/revoke` |
| Sign-out | `https://auth.voozin.com/api/auth/oauth2/end-session` |

Websites authenticate to the token endpoint with HTTP Basic (`client_secret_basic`). Every authorization request needs PKCE with `S256`, websites included.

## Scopes

| Scope | Grants |
| --- | --- |
| `openid` | An ID token with the user's ID in `sub`. |
| `profile` | The user's name. |
| `email` | The user's email address and whether it is verified. |
| `offline_access` | A refresh token, so the app stays signed in after the access token expires. |
| `mail` | IMAP and SMTP for mailboxes the user can open. Needs **Mail and calendar access**. |
| `calendar` | CalDAV for those mailboxes' calendars. Needs **Mail and calendar access**. |

Access tokens last one hour. `sub` is a stable user ID; use it, not the email address, to link accounts.

## Node.js example

A website using [openid-client](https://github.com/panva/openid-client) (version 6) and Express:

```ts
import express from "express";
import session from "express-session";
import * as client from "openid-client";

const config = await client.discovery(
  new URL("https://auth.voozin.com"),
  process.env.VOOZIN_CLIENT_ID!,
  undefined,
  client.ClientSecretBasic(process.env.VOOZIN_CLIENT_SECRET!),
);
const redirectUri = "https://example.com/auth/callback";

const app = express();
app.use(session({ secret: process.env.SESSION_SECRET!, resave: false, saveUninitialized: false }));

app.get("/auth/voozin", async (req, res) => {
  const verifier = client.randomPKCECodeVerifier();
  const state = client.randomState();
  req.session.oauth = { verifier, state };
  const url = client.buildAuthorizationUrl(config, {
    redirect_uri: redirectUri,
    scope: "openid email profile",
    code_challenge: await client.calculatePKCECodeChallenge(verifier),
    code_challenge_method: "S256",
    state,
  });
  res.redirect(url.href);
});

app.get("/auth/callback", async (req, res) => {
  const { verifier, state } = req.session.oauth ?? {};
  const tokens = await client.authorizationCodeGrant(config, new URL(req.originalUrl, "https://example.com"), {
    pkceCodeVerifier: verifier,
    expectedState: state,
  });
  const claims = tokens.claims()!;
  req.session.user = { id: claims.sub, email: claims.email, name: claims.name };
  req.session.idToken = tokens.id_token; // needed to sign out
  res.redirect("/");
});
```

## PKCE without a library

Apps follow the same steps by hand.

1. Make a random `code_verifier` (43 to 128 characters) and its challenge: the base64url SHA-256 hash of the verifier.
2. Open the authorization URL in the system browser:

```text
https://auth.voozin.com/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
  &scope=openid%20email%20mail%20offline_access
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
```

3. The user signs in, approves the app and comes back to your redirect URI with `code`, `state` and `iss`. Check that `state` matches and `iss` is `https://auth.voozin.com`.
4. Exchange the code:

```bash
curl https://auth.voozin.com/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=CODE_FROM_REDIRECT \
  -d redirect_uri=http://127.0.0.1:53682/callback \
  -d code_verifier=CODE_VERIFIER
```

The response has `access_token`, `expires_in`, `id_token` (with `openid`) and `refresh_token` (with `offline_access`). Get a new access token with `grant_type=refresh_token`; each refresh returns a new refresh token, so store it.

## Signing out

Signing someone out of your app never signs them out of Voozin. They stay signed in to the Voozin dashboard, webmail and other apps, and the next **Sign in with Voozin** goes straight through without a password. Add `prompt=login` to the authorization URL if you want Voozin to ask for the password again.

To sign someone out, clear your own session, then send the browser to the sign-out endpoint. Voozin revokes the tokens your app got from that sign-in, including the refresh token, and sends the person back to you.

| Parameter | |
| --- | --- |
| `id_token_hint` | The ID token you got at sign-in. Voozin uses it to find which tokens to revoke. |
| `client_id` | Your client ID. Needed when you don't send `id_token_hint`. |
| `post_logout_redirect_uri` | Optional. Where to send them afterwards. It must exactly match one of the app's **Sign-out redirect URIs**; otherwise Voozin shows an error. Without it, Voozin shows a "Signed out" page. |
| `state` | Optional. Returned on the redirect as `state`. |

With openid-client, continuing the example above (add `https://example.com/signed-out` under **Sign-out redirect URIs** first):

```ts
app.post("/logout", (req, res) => {
  const idToken = req.session.idToken;
  req.session.destroy(() => {});

  const url = client.buildEndSessionUrl(config, {
    id_token_hint: idToken!,
    post_logout_redirect_uri: "https://example.com/signed-out",
  });
  res.redirect(url.href);
});
```

Without a library, redirect to:

```text
https://auth.voozin.com/api/auth/oauth2/end-session
  ?id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https%3A%2F%2Fexample.com%2Fsigned-out
  &state=RANDOM_STATE
```

Apps that don't want a redirect, such as desktop and mobile apps, can revoke the refresh token at the revocation endpoint instead and then forget their tokens:

```bash
curl https://auth.voozin.com/api/auth/oauth2/revoke \
  -d client_id=YOUR_CLIENT_ID \
  -d token=REFRESH_TOKEN \
  -d token_type_hint=refresh_token
```

Websites send their client secret with HTTP Basic, as at the token endpoint. ID tokens issued before 13 November 2026 don't name the sign-in, so for those the sign-out endpoint only redirects; revoke the refresh token as above.

## Mail and calendar access

With the `mail` scope, the access token signs in to IMAP and SMTP with SASL `XOAUTH2` or `OAUTHBEARER`. With `calendar`, it signs in to CalDAV as a `Bearer` token.

| Service | Server |
| --- | --- |
| IMAP | `imap.inboxcluster.net`, port `993` (TLS) |
| SMTP | `smtp.inboxcluster.net`, port `465` (TLS) or `587` (STARTTLS) |
| CalDAV | `https://mail.voozin.com/dav/` |

The user name is the mailbox address, for example `ann@acme.com`. The token's user must be able to open that mailbox in Voozin; a token works for every mailbox they can open. For CalDAV, `https://mail.voozin.com/dav/` opens the mailbox at the user's own address (or their only mailbox); for any other mailbox, use its principal URL, such as `https://mail.voozin.com/dav/principals/ann@acme.com/`.

An `XOAUTH2` login is the base64 encoding of:

```text
user=ann@acme.com^Aauth=Bearer ACCESS_TOKEN^A^A
```

where `^A` is the byte `0x01`. With Nodemailer:

```ts
const transport = nodemailer.createTransport({
  host: "smtp.inboxcluster.net",
  port: 465,
  secure: true,
  auth: { type: "OAuth2", user: "ann@acme.com", accessToken },
});
```

When a token is expired or lacks the scope, the server answers with a JSON challenge as in [RFC 7628](https://www.rfc-editor.org/rfc/rfc7628): `{"status":"invalid_token","scope":"mail","openid-configuration":"https://auth.voozin.com/.well-known/openid-configuration"}`. Reply with the dummy response `AQ==` (the byte `0x01`), which fails the login, then refresh the token and sign in again. CalDAV answers `401` with a `WWW-Authenticate: Bearer` header naming the missing scope.

Mailboxes with end-to-end encryption have no CalDAV.

## Revoking access

People see the apps they've approved under **Account and security → Connected apps** in the dashboard, and **Disconnect** revokes the app's tokens at once. Apps can revoke their own refresh token at the revocation endpoint when someone signs out (see [Signing out](#signing-out)). Disabling or deleting an app under **Developer apps** stops it for everyone.

## Sign in with Voozin button

Use the official button, in [dark](https://voozin.com/sign-in-with-voozin.svg) or [light](https://voozin.com/sign-in-with-voozin-light.svg):

![Sign in with Voozin](https://voozin.com/sign-in-with-voozin.svg) ![Sign in with Voozin, light](https://voozin.com/sign-in-with-voozin-light.svg)

```html
<a href="/auth/voozin">
  <img src="https://voozin.com/sign-in-with-voozin.svg" width="240" height="44" alt="Sign in with Voozin" />
</a>
```
