Skip to main content
MeetCost has no user accounts of its own. It verifies bearer tokens that your identity provider already issues — the same Google, Microsoft, Okta, or Keycloak tenant your calendar and email run on. When a user opens the admin console or a calendar add-in calls the API, it presents a token it obtained from your IdP. MeetCost validates the token’s signature against the IdP’s JWKS, checks the audience, and extracts the user’s email from the configured claim. No passwords are stored, no sessions are issued by MeetCost itself, and there is nothing for users to register.

​
How OIDC verification works

Set MEETCOST_AUTH_MODE=oidc and provide MEETCOST_OIDC_ISSUER. MeetCost fetches the OIDC discovery document from <issuer>/.well-known/openid-configuration at startup and reads the JWKS endpoint from it. All token verification is local after that — no call to the IdP is made per-request.
MEETCOST_AUTH_MODE=dev accepts locally-signed tokens for local development. It is refused when MEETCOST_ENVIRONMENT=production. Never configure dev mode for a deployment that handles real pay data.

​
Identity provider configuration

Google tokens include the user’s email in the email claim by default — no need to set MEETCOST_OIDC_EMAIL_CLAIM.The Meet add-on’s ScriptApp.getIdentityToken() produces a Google-signed JWT that MeetCost can verify directly, without any additional OAuth flow in the add-on.

​
Non-standard email claims

MeetCost reads the user’s email from the email JWT claim by default. If your identity provider uses a different claim name, set:
Common alternatives:

​
Admin console and SSO proxy integration

The admin console stores the caller’s token in sessionStorage for the tab’s lifetime. The recommended production posture is to place MeetCost behind the SSO proxy you already operate:

oauth2-proxy

Configure oauth2-proxy to validate tokens and pass them upstream as Authorization: Bearer <token> or X-Forwarded-Access-Token. MeetCost reads from Authorization by default.

Pomerium

Pomerium can inject identity headers at the proxy layer. Configure the pass_identity_headers policy to forward the JWT to MeetCost.

Cloudflare Access

Cloudflare Access issues its own signed JWT in the Cf-Access-Jwt-Assertion header. Configure MEETCOST_OIDC_ISSUER to your Access team domain and set MEETCOST_OIDC_AUDIENCE to your Access application AUD tag.
The SSO proxy approach means your ingress enforces authentication before any request reaches MeetCost’s application layer. Users who are not in your IdP cannot reach the service at all.

​
Machine callers: service tokens

Cron jobs, webhook relays, and other automated systems that call the API use static service tokens rather than OIDC tokens. Configure them with:
The format is name:token pairs, comma-separated. The name is for your reference only (it appears in audit log entries). Callers pass the token as a standard bearer token:
Service tokens carry admin-level rights. Treat them with the same care as admin credentials. Rotate them on the same schedule as your other privileged secrets. If a token is compromised, remove it from MEETCOST_SERVICE_TOKENS and restart the service — the old token is immediately invalidated.
Tokens are matched in constant time to prevent timing attacks.

​
Bootstrap admins

On first boot, before any role rows exist in the database, MeetCost needs at least one admin. Use MEETCOST_BOOTSTRAP_ADMINS to pre-grant the admin role to one or more email addresses:
These emails are granted the admin role each time the service starts. Once you have a working admin user who can manage roles through the UI or CLI, this variable’s effect is idempotent — setting it to a real admin’s email is harmless to leave in place.
On Kubernetes, pass this via --set config.bootstrapAdmins=alice@your-company.example in the helm install command. You can remove it or leave it as-is after the first login.

​
Development tokens

In development mode (MEETCOST_ENVIRONMENT=development, MEETCOST_AUTH_MODE=dev), the CLI can mint locally-signed tokens for any email address:
This prints a JWT to stdout that can be used as a bearer token against the local service. It is useful for testing API calls and the admin console without an identity provider configured.
meetcost token is refused when MEETCOST_ENVIRONMENT=production. It exists only for local development. Never use development tokens against a production deployment.

​
Role management

MeetCost has five roles: Assign roles with the meetcost grant CLI command:
The --team-id flag is used with the team_lead role to scope access to a specific team. Without it, a team_lead has no team-scoped access. You can also manage roles through the admin console UI once at least one admin is logged in.

​
Authentication flow summary

There is no session issued by MeetCost. Each request is authenticated independently against the presented token.