SuperTokens

Feature availability

Feature	Support
User management	✅ Full
Organizations	✅ Via multi-tenancy (each tenant = one organization)
Audit logs	❌ Not supported

Caution

SuperTokens does not expose a native audit log API. Use an external logging solution (e.g. your database audit log or an observability platform) if you need audit trails.

Setup

1. Run the SuperTokens core

   Self-host the SuperTokens core or use SuperTokens managed cloud.

   For local development with Docker:

   docker run -d \
     -p 3567:3567 \
     registry.supertokens.io/supertokens/supertokens-postgresql

   Note the connection URI (e.g. http://localhost:3567) and, if you have configured one, the API key in your config.yaml.

2. Configure your SuperTokens backend SDK

   AUMS connects directly to the SuperTokens core using the CDI (Core Driver Interface). Your application’s backend SDK (Node.js, Python, etc.) must already be initialized with the EmailPassword and, optionally, the EmailVerification, UserMetadata, and Multitenancy recipes enabled.

   AUMS relies on these recipes for full user management:

   Recipe	Purpose in AUMS
   EmailPassword	Create and update users (required)
   EmailVerification	Mark emails as verified / unverified
   UserMetadata	Store user display name (first / last name)
   Multitenancy	Manage organizations as SuperTokens tenants

3. Set environment variables

   PROVIDER=supertokens
   SUPERTOKENS_CONNECTION_URI=http://localhost:3567
   
   # Required for SuperTokens managed cloud, optional for self-hosted
   # SUPERTOKENS_API_KEY=your-api-key
   
   # Tenant used for user operations (default: public)
   # SUPERTOKENS_TENANT_ID=public

Note

AUMS communicates directly with the SuperTokens core over the CDI. The SUPERTOKENS_CONNECTION_URI must be reachable from the AUMS server process — do not expose it to the internet.

Organizations

SuperTokens multi-tenancy maps directly to AUMS organizations: each SuperTokens tenant (other than the default tenant configured by SUPERTOKENS_TENANT_ID) is treated as an organization.

AUMS operation	SuperTokens CDI call
List orgs	GET /recipe/multitenancy/tenant/list/v2
Create org	PUT /recipe/multitenancy/tenant (tenantId = slug of name)
Delete org	POST /recipe/multitenancy/tenant/remove
List members	GET /{tenantId}/users
Add member	POST /recipe/multitenancy/tenant/user
Remove member	DELETE /recipe/multitenancy/tenant/user

Caution

Organization names are converted to a URL-safe tenant ID (lowercase, alphanumeric, hyphens). Tenant IDs are immutable once created — renaming an organization in AUMS does not change the underlying tenant ID.

Note

Invitations are not supported. Add users via the AUMS user management interface, then assign them to an organization.

User management notes

• Password required — AUMS creates users via the EmailPassword recipe. A password must be provided when creating a user.
• Display name — First and last name are stored in the UserMetadata recipe under the keys first_name and last_name.
• Blocked users — SuperTokens has no native block/suspend concept. The blocked field always returns false; block operations are silently ignored.
• Email verification — Requires the EmailVerification recipe to be enabled in your SuperTokens backend SDK.

OIDC login (optional)

To protect the AUMS dashboard with SuperTokens SSO, configure an OIDC provider that wraps your SuperTokens deployment (e.g. via the OAuth2 provider recipe):

AUTH_CLIENT_OPENID_CONFIGURATION_URL=https://your-supertokens-app/.well-known/openid-configuration
AUTH_CLIENT_ID=your-oidc-client-id
AUTH_CLIENT_SECRET=your-oidc-client-secret