Workspace

Single sign-on

Let your team sign in through your company's identity provider (Okta, Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, Auth0 and others) over SAML 2.0 or OpenID Connect.

Availability

Single sign-on is part of the Scale and Enterprise plans, for team workspaces. Each workspace has one connection, managed by its owners and admins in Settings › Team › Single sign-on.

How sign-in works

People choose Continue with SSO on the sign-in page and enter their work email. Token Meter finds the workspace that verified the address's domain and sends them to that workspace's identity provider. When they come back they are signed in to that workspace.

Sign-in always starts from Token Meter. Responses the identity provider sends on its own (an app tile on the provider's dashboard, sometimes called IdP-initiated sign-in) are refused, because nothing ties them to a sign-in this browser started.

Set it up

1. Verify your email domains

Add each domain your people's addresses use (acme.com, eu.acme.com). For each one Token Meter shows a DNS TXT record to publish:

Field	Value
Name	`_tokenmeter-verification.acme.com`
Value	`tokenmeter-verify=<token shown in Settings>`

Publish it with your DNS provider, then choose Verify. DNS changes can take a few minutes to appear. The record can be removed once the domain is verified.

Your identity provider is only trusted for addresses on verified domains. A sign-in that names any other address is refused.
A verified domain belongs to one Token Meter workspace.
Shared mailbox domains (gmail.com, outlook.com and the like) cannot be added.

2. Create an app in your identity provider

Settings shows the values to copy, specific to your workspace and your Token Meter address.

SAML 2.0

Your provider asks for	Use
ACS URL, Reply URL or Single sign-on URL	`https://<your Token Meter address>/api/auth/sso/saml/<workspace id>/acs`
Entity ID, Audience or Identifier	`https://<your Token Meter address>/api/auth/sso/saml/<workspace id>/metadata`
SP metadata URL (if it can import one)	the same metadata URL

The assertion must be signed. Signing the whole response as well is fine. SHA-256 is recommended.
Send the user's email address as the NameID (format EmailAddress) or as an attribute named email, mail or the standard email address claim. A name attribute (displayName, or firstName and lastName) is used when present.
Token Meter sends unsigned AuthnRequests over HTTP-Redirect and receives the response over HTTP-POST.

OpenID Connect

Your provider asks for	Use
Redirect URI or Sign-in redirect URI	`https://<your Token Meter address>/api/auth/sso/oidc/callback`
Grant type	Authorization code (Token Meter uses PKCE)
Scopes	`openid email profile`

The address comes from the email claim, or from preferred_username or upn when there is no email claim (Microsoft Entra ID). The client is authenticated with client_secret_basic, or client_secret_post when the provider supports only that.

3. Enter the connection in Token Meter

SAML: the provider's SSO URL, its entity ID (Issuer) and its X.509 signing certificate in PEM form.
OpenID Connect: the issuer URL, client ID and client secret. Token Meter reads <issuer>/.well-known/openid-configuration when you save, so a wrong issuer is caught straight away. The secret is stored encrypted and never shown again; leave it blank later to keep it.

Also choose the role people get when they first join through SSO: Member or Admin. Nobody joins as an owner.

4. Test a sign-in

Use Test sign-in in Settings with an address on a verified domain. The browser is then signed in as whoever your identity provider names. Settings shows the time of the last successful sign-in and the last error.

5. Require SSO (optional)

Once a test sign-in has worked you can turn on Require SSO. See Require SSO for what it changes.

Who gets in

New people on a verified domain join the workspace on their first SSO sign-in with the role you chose, and take a seat. When the workspace has no free seat, the sign-in is refused until a seat is free.
Existing members sign in to their existing account; their role does not change.
Removed members stay removed. An admin's removal outranks the identity provider; invite them again to restore access.
Existing Token Meter accounts with the same email are linked to the identity provider on first SSO sign-in. If that account's email was never verified, the identity provider has now proven who owns the address, so the account's password is removed and its other sessions are signed out.

Offboarding

Removing someone in your identity provider stops new SSO sign-ins. To end access to Token Meter straight away, also remove them in Settings › Team › People.

Require SSO

When it is on, password and Google sign-in are refused for every address on your verified domains, with a message pointing to Continue with SSO.

Owners are exempt. The workspace's owners can still sign in with a password, so a broken identity provider can always be fixed.
It needs a working connection. It can only be turned on after a successful SSO sign-in, and changing the connection's settings turns it off until a sign-in through the new settings works.
Addresses outside your verified domains are not affected, for example contractors invited with their own addresses.
Sessions already signed in stay signed in until they expire or are signed out.

Certificates and changes

Rotating a SAML certificate: paste both the current and the new certificate into the certificate field. A response signed by either is accepted. Remove the old one after the switch.
Changing provider or protocol: save the new settings over the old ones. The service provider URLs stay the same, because they belong to the workspace rather than the connection.
Remove connection returns everyone to password and Google sign-in. Nobody loses workspace access.

Provider notes

Okta (SAML). Create a SAML 2.0 app integration. Set Single sign-on URL to the ACS URL, Audience URI (SP Entity ID) to the entity ID, Name ID format to EmailAddress and Application username to Email. From the app's sign-on details copy the Identity Provider Single Sign-On URL, Identity Provider Issuer and X.509 certificate.

Microsoft Entra ID (SAML). Create an Enterprise application with SAML single sign-on. Set Identifier (Entity ID) to the entity ID and Reply URL (Assertion Consumer Service URL) to the ACS URL. Copy the Login URL, the Microsoft Entra Identifier and the Certificate (Base64).

Microsoft Entra ID (OpenID Connect). Register an app with a Web redirect URI set to the redirect URI and create a client secret. The issuer is https://login.microsoftonline.com/<tenant id>/v2.0.

Google Workspace (SAML). In the Admin console add a custom SAML app. Copy its SSO URL, Entity ID and certificate, then set ACS URL and Entity ID to Token Meter's values, Name ID format to EMAIL and Name ID to Primary email. Turn the app on for the users who need it.

Troubleshooting

Message	What to check
Single sign-on isn't set up for that email domain	The address's domain is not verified in any workspace, or the workspace has no connection.
That email address isn't on a domain this workspace has verified	The identity provider sent an address on another domain. Verify that domain or change the address the provider sends.
Your identity provider didn't send an email address	Add the email as NameID or an `email` attribute (SAML), or grant the `email` scope (OpenID Connect).
This workspace has no free seats	Free a seat in Settings › Team › People, or move to a plan with more seats in Settings › Billing.
Your access to this workspace was removed	An admin removed this person; invite them again.
Start single sign-on from the Token Meter sign-in page	The provider sent a response this browser didn't ask for (an app tile, or an attempt older than 10 minutes). Start again from Continue with SSO.
Couldn't sign in with single sign-on	The response was rejected. Settings › Team › Single sign-on shows the reason as the last error: a signature, issuer or audience mismatch, or an expired assertion (check the provider's clock).

Security

Your identity provider is trusted only for addresses on domains your workspace has proven it owns with DNS, so a misconfigured or hostile provider cannot sign anyone in as an address outside them.
SAML assertions must be signed by a certificate you configured, issued by your configured entity ID, addressed to your workspace's entity ID, within their validity window, and in answer to the request this browser started within the last 10 minutes.
OpenID Connect uses the authorization code flow with PKCE and a nonce, and the ID token's signature, issuer, audience and expiry are checked against your provider's published keys.
OpenID Connect client secrets are stored with envelope encryption. SAML needs no secret.
Every change to domains, the connection and Require SSO is recorded in the workspace's audit log.