SuperTokens authentication core

v0.1.0

Diagnostics and user operations for a SuperTokens core over its HTTP API: health, versions, request rates, licensed features, settings, tenants and the 12.x migration; users, sessions, roles and dashboard admins; and signing out, granting or removing a role, and deleting a user. The core API key and searched emails and phone numbers are streamed over curl stdin; client secrets, session data, the database password and other secret settings never leave the host.

19 allowed by default 4 need approval by default 1 denied by default

Pack ID

supertokens

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.


              curl

jq

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host

sudo emisar pack install supertokens --hash sha256:13d72d33c0b5fa766b94ebb74195d226500a37801d3120d2a347085a24b01a54

Setup

Every action calls the SuperTokens core HTTP API at $SUPERTOKENS_URL via curl on the runner host. The API key is read from $SUPERTOKENS_API_KEY and sent as the api-key header over curl stdin, so it never appears in the process arguments or the audit log.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

SUPERTOKENS_URL default http://127.0.0.1:3567

Base URL of the core — scheme, host, and port, plus any base_path or /appid-<id> prefix the core serves under. Each action appends its path (e.g. /hello, /users/count).
SUPERTOKENS_API_KEY

One of the comma-separated keys in the core's api_keys setting ( API_KEYS in the Docker image); each key is at least 20 characters of A-Z a-z 0-9 = - . The core has no read-only or scoped key — any key can delete users — so add a dedicated key for the runner to rotate it on its own; the actions' risk tiers and the account policy are the only gate. Leave it unset only when the core sets no api_keys .

Notes

Any of SUPERTOKENS_URL / SUPERTOKENS_API_KEY you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
Actions address the app in SUPERTOKENS_URL and its public tenant. App-level reads such as user counts and user lookups cover every tenant; roles and email lookups are per tenant, and tenants other than public need a multitenancy license.
delete_user is critical and so denied by the default policy; an account enables it deliberately, for example for GDPR erasure.
The core keeps no live session count and reports no release number: active_users and user_sessions stand in for the first, api_version for the second. It keeps no failed-login count for passwords, and its logs go to the container's stdout.
User metadata is not read: SuperTokens documents storing a provider's OAuth tokens there.

Verify it works

Runs supertokens.api_version, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify supertokens

Install and configure a pack walks through the whole sequence on a host.

Actions 24 total

View on GitHub

supertokens.active_users script low

Count recently active users

Count users whose session was created or refreshed within the last window_minutes with GET /users/count/active. The core keeps no live session count, so this is the nearest measure of who is signed in. Core 12 records refresh activity at most every 5 minutes.
View source on GitHub
supertokens.add_user_role script high

Grant a role to a user

Grant an existing role to a user in the public tenant with PUT /recipe/user/role, after looking the user up; the core would otherwise store a grant for an id that matches no user. Fails with UNKNOWN_USER_ID_ERROR or UNKNOWN_ROLE_ERROR; roles are defined by the app. already_had_role true means nothing changed. Live sessions see the role when their role claim refreshes; supertokens.revoke_user_sessions applies it at once. supertokens.remove_user_role reverses it.
View source on GitHub
supertokens.api_version script low

Show supported core API versions

Show the core driver interface (CDI) versions this SuperTokens core supports with GET /apiversion, sorted, with the newest as latest. A backend SDK needs one of them, so this explains SDK version errors after an upgrade. The core reports no release number; the newest CDI stands in for it: 5.4 is core 11.x, 5.5 is 12.0.8 or later, and 5.6 is 12.1 or later. Needs the API key when the core sets api_keys.
View source on GitHub
supertokens.config script low

Show core settings

Show the core's effective settings from GET /recipe/dashboard/tenant/core-config (core 9.1 or later): token lifetimes, password hashing, IP allow and deny rules, and the database host, port, name and pool. Token validity is in seconds, refresh_token_validity in minutes, and the other lifetimes in milliseconds. Only a fixed list of settings leaves the host with values, as name and value rows; every other setting, including the database user, password and connection URI, is listed by name under withheld. non_default names every setting that differs from the core's default.
View source on GitHub
supertokens.dashboard_users script low

List dashboard admins

List the people who can sign in to the SuperTokens user-management dashboard, with GET /recipe/dashboard/users: each one's id, email and join time. The core never returns their password hashes. Without a dashboard license the core allows at most 3 of them.
View source on GitHub
supertokens.delete_user script critical

Delete a user

Delete a user with POST /user/remove, after looking the user up so an unknown id fails instead of reporting success, then read the user back. Irreversible: removes the user's login methods, sessions, roles, metadata, email-verification state, TOTP devices and external id mapping. The app's own data about the user is untouched. With all_linked_accounts false, only this login method goes and a linked account's other login methods remain, so deleted reports false while any remain. The output carries no email addresses.
View source on GitHub
supertokens.find_user script medium

Find users by email, phone or social login

Find users by one exact account detail with GET /users/by-accountinfo: an email address, a phone number, or a third-party provider id with the user's id at that provider. Returns each match's email addresses and phone numbers, login methods and verification state. The core lower-cases emails and normalises phone numbers before matching. No match is a count of 0.
View source on GitHub
supertokens.hello script low

Check SuperTokens core health

Check that the SuperTokens core is up and can reach its database with GET /hello. Returns "Hello", or fails with a 500 that names the storage error when the database is unreachable. Needs no API key.
View source on GitHub
supertokens.migration_status script low

Show the 12.x schema migration status

Show the schema migration mode and the users still waiting for the backfill for each connection URI domain, from GET /migration/backfill/progress (core 12.0 or later). Core 12 reworked its tables, and a PostgreSQL deployment walks from LEGACY to MIGRATED; a fresh one starts in LEGACY. Core 11.x answers 404 Not found.
View source on GitHub
supertokens.passwordless_codes script low

Show pending passwordless codes for a user

Show the pending passwordless sign-in codes for an email address or phone number with GET /recipe/signinup/codes: for each device, how many wrong codes were entered and when each code was created and expires. The core never returns the code or magic link here.
View source on GitHub
supertokens.remove_user_role script high

Remove a role from a user

Remove a role from a user in the public tenant with POST /recipe/user/role/remove, after looking the user up. Fails with UNKNOWN_USER_ID_ERROR or UNKNOWN_ROLE_ERROR. had_role false means the user did not hold it and nothing changed. Live sessions lose the role when their role claim refreshes; supertokens.revoke_user_sessions applies it at once. supertokens.add_user_role reverses it.
View source on GitHub
supertokens.request_stats script low

Show core request rates

Show the average and peak requests per second this SuperTokens core process served over the last minute, 5 minutes, hour and 24 hours, from GET /requests/stats. The core keeps these in memory per process, so they reset on restart, and in a cluster each core reports only itself.
View source on GitHub
supertokens.revoke_session script high

Sign out one session

Revoke one session by its handle with POST /recipe/session/remove, the dashboard's per-device sign-out. Fails when no live session has the handle, since the core answers OK for one that is already revoked or expired. The session's refresh token is refused at once; its current access token stays valid until it expires unless the backend checks sessions against the database. supertokens.user_sessions lists the handles.
View source on GitHub
supertokens.revoke_user_sessions script high

Sign a user out everywhere

Revoke every session of a user across all tenants and linked accounts with POST /recipe/session/remove, after looking the user up so an unknown id fails instead of revoking nothing. The core refuses the user's refresh tokens at once, but an access token it already issued stays valid until it expires (access_token_validity, one hour by default) unless the backend checks sessions against the database. Revoking counts as activity for supertokens.active_users. The core has no suspend API; SuperTokens' documented ban is a role the app denies, granted with supertokens.add_user_role, plus this revocation.
View source on GitHub
supertokens.role_users script low

List the users who hold a role

List the ids of the users who hold a role in the public tenant with GET /recipe/role/users, with the total count. The core returns every holder, so the list is capped on the host at limit and truncated says when it was cut. Fails with UNKNOWN_ROLE_ERROR when the role does not exist.
View source on GitHub
supertokens.roles script low

List roles and their permissions

List every role the app defined in the SuperTokens user-roles recipe with its permissions, from GET /recipe/roles and GET /recipe/role/permissions for each role. Permissions are read for at most 200 roles; beyond that truncated is true.
View source on GitHub
supertokens.signing_keys script low

List access-token signing keys

List the public keys the core signs access tokens with, from GET /.well-known/jwks.json: each key id, algorithm and type, whether it is a dynamic key, and when a dynamic key was created. Dynamic keys rotate on access_token_dynamic_signing_key_update_interval (168 hours by default), so this explains "kid not found" token verification failures.
View source on GitHub
supertokens.tenants script low

List tenants and their login methods

List every tenant with GET /recipe/multitenancy/tenant/list/v2 (core 9.1 or later): its id, first and required secondary factors (null means the core default), each third-party provider with its public OAuth client ids and scopes, and the names of its core config overrides. Client secrets, private keys, token-endpoint parameters and override values are dropped on the host; confidential says whether a client has a secret.
View source on GitHub
supertokens.usage_stats script low

Show licensed features and active users

Show which paid features the core's license enables and how many users were active in the last 1, 7 and 30 days, from GET /ee/featureflag. active_by_days[i] counts users active in the last i+1 days. Licensed features add counts per feature, such as tenants and their user counts. A core with the in-memory store reports every feature as enabled.
View source on GitHub
supertokens.user script medium

Show one user

Show one user with GET /user/id. Returns the user's email addresses and phone numbers, each login method with its email-verification state, the tenants the user belongs to, third-party ids, and whether accounts are linked. Accepts a SuperTokens user id or an external id the app mapped to it. Fails with UNKNOWN_USER_ID_ERROR when no such user exists. supertokens.user_roles and supertokens.user_sessions show the user's roles and sessions.
View source on GitHub
supertokens.user_count script low

Count SuperTokens users

Count users across every tenant with GET /users/count, optionally only those with one login method. The core counts exactly; a pending passwordless code is not a user until it is consumed.
View source on GitHub
supertokens.user_roles script low

Show a user's roles and permissions

Show the roles a user holds in the public tenant with GET /recipe/user/roles, and the union of those roles' permissions, which is what the SDK's permission claim carries. Fails with UNKNOWN_USER_ID_ERROR for an unknown user. A change reaches a live session only when its role claim refreshes; supertokens.user_sessions shows what each session carries.
View source on GitHub
supertokens.user_sessions script low

List a user's sessions

List a user's live sessions across every tenant and linked account with GET /recipe/session/user, then GET /recipe/session for each: the session handle, tenant, when it was created and when its refresh token expires, and the values of the SuperTokens role, permission, email-verification and MFA claims in its access token. Only the key names of the rest of the access-token payload and of the session data leave the host, since the app defines them. Fails with UNKNOWN_USER_ID_ERROR for an unknown user.
View source on GitHub
supertokens.users script medium

List users

List users newest or oldest first with GET /users, one page at a time. Returns each user's email addresses, phone numbers, login methods and verification state. Filters narrow the list to one login method, one third-party provider, or an email search that matches an address prefix or a domain, so example.com lists everyone at that domain. Pass next_page_cursor back as page_cursor for the next page.
View source on GitHub

← Back to registry

Pack reference Publish your own