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
- 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.
- Choose the type:
- Website: your server keeps a client secret. Redirect URIs use
https(http://localhostworks 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 ascom.example.app:/oauth.
- Website: your server keeps a client secret. Redirect URIs use
- Tick Mail and calendar access if the app needs IMAP, SMTP or CalDAV.
- Optionally add Sign-out redirect URIs: the pages people may return to after signing out of your app (see Signing out). They follow the same rules as redirect URIs.
- 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 (version 6) and Express:
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.
- Make a random
code_verifier(43 to 128 characters) and its challenge: the base64url SHA-256 hash of the verifier. - Open the authorization URL in the system browser:
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- The user signs in, approves the app and comes back to your redirect URI with
code,stateandiss. Check thatstatematches andissishttps://auth.voozin.com. - Exchange the code:
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_VERIFIERThe 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):
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:
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_STATEApps 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:
curl https://auth.voozin.com/api/auth/oauth2/revoke \
-d client_id=YOUR_CLIENT_ID \
-d token=REFRESH_TOKEN \
-d token_type_hint=refresh_tokenWebsites 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:
user=ann@acme.com^Aauth=Bearer ACCESS_TOKEN^A^Awhere ^A is the byte 0x01. With Nodemailer:
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: {"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). Disabling or deleting an app under Developer apps stops it for everyone.
Sign in with Voozin button
Use the official button, in dark or light:
<a href="/auth/voozin">
<img src="https://voozin.com/sign-in-with-voozin.svg" width="240" height="44" alt="Sign in with Voozin" />
</a>