Manage end users #
On this page
Prompt:
Invite sam@example.com to my app, and show me who has signed up so far.
Also works:
- "Suspend this user; they have been abusing the site."
- "Our sign-in keys may have leaked. Make every user sign in again."
- "Remove this person and everything about them from my app."
- "Keep people signed in for a week instead of a month."
Invite people, inspect users, suspend or delete an account, and configure sign-in with the actions below. Each application's environment has a separate realm; calls default to production unless stated otherwise.
What your AI tool does #
- Reads the
add-sign-inskill (read_context, idskill:add-sign-in) and follows it. - When you ask who is invited or who has signed up, calls
tzcloud_list_invitationsandtzcloud_list_end_users, followingnext_cursoruntil it isnull. - Suspends a user and restores one with
tzcloud_set_end_user_standing, passingstanding: suspendedorstanding: active, with no browser approval, because it is a reversible-tier action. - For a deletion, calls
tzcloud_delete_end_user, gives you the approval link, and reads the outcome withread_approval_statusafter you approve in the browser. No tool approves in your place. - For a suspected key compromise, calls
tzcloud_revoke_app_sign_in_keysfor the environment, and tells you that every user of that realm must sign in again. - Reads the realm with
tzcloud_read_app_sign_inbeforetzcloud_configure_app_sign_inchanges a setting, once for each environment's realm. - Asks you for each address to invite where the prompt gives none. It reports every value it configured, every invitation URL, and every change it made to a user's
standing.
What you need #
- For invitation-only sign-up, the email addresses to invite and a way to deliver each invitation URL yourself.
Before your AI starts #
For the AI tool: Check the following before starting.
- A connected, signed-in AI tool (Connect your AI assistant).
- An application, whose identifier
tzcloud_list_applicationsreturns, and a manifest that declares the accounts service (Add sign-in to your app). - For this page's realm and end-user actions, leaving out
environmentselects production, excepttzcloud_revoke_app_sign_in_keys, which requires it.
Steps #
Name application in each call below, and environment: "development" for the development realm. Identifiers are the values the matching list or creation action returned.
1. Invite people #
Call tzcloud_invite_end_user with the person's email, leaving out invitation. It returns an invitation with its id, email, a single-use url, and expires_at, 14 days away by default. The platform does not email it, so deliver the URL yourself. Open creation needs no invitations, and products is refused here.
{ "application": "<application id>", "email": "sam@example.com" }
Opening the URL opens the application's sign-in page with the realm's sign-in methods. The page shows nothing of the invitation, so a spent or expired URL looks the same. The person signs in with a route that verifies the invited address. Make sign-up invitation-only turns invitation-only sign-up on.
tzcloud_invite_end_user with the invitation's identifier in invitation returns that identifier and revoked_at. Leave out email and products in this form. A redeemed invitation is unchanged, and a revoked one keeps its first revocation time.
An invitation issued before an application rename contains the old hostname, which no longer responds. Its token still works. If you kept the URL, replace the hostname with the new one before sending it. Otherwise revoke the invitation and issue a new one.
2. List invitations and users #
tzcloud_list_invitations takes an optional email, limit, and cursor, and returns invitations and next_cursor. Each row contains the identifier, address, times of issue, expiry, redemption, and revocation, redeemed_by, and a state: standing, redeemed, revoked, or expired. An email keeps only that address's invitations, ignoring case and surrounding spaces. The URL is never returned again.
tzcloud_list_end_users takes an optional limit and cursor, and returns end_users and next_cursor. Each row contains id, created_at, standing, routes, email (which may be null), and email_verified. Where the address comes from the work-account tenant, the row also has email_source set to tenant, and email_verified is true only where the tenant's token stated the domain owner verified it. A test end user's row also has test: true and its expires_at.
Testers who signed in to production are ordinary end users, with no tester marker. Only test end users have test: true. Ask the person for the testers' addresses and match them to the listed users. At the person's word, suspend or delete those users as step 3 describes; deletion also needs browser approval. Turning development on leaves production's users in place.
A user who signs in by code with an address their Google or GitHub identity already verified reaches the same user, with the new route added, and routes lists it.
Both list actions return 50 rows by default and accept a limit from 1 to 200. Rows are ordered by creation time, then identifier. Pass next_cursor to fetch the next page; null means there is none. A cursor works only with the email filter that produced it. If the cursor's row no longer exists, start again from the first page. Separate requests do not share one snapshot.
3. Suspend, delete, or sign everyone out #
tzcloud_set_end_user_standingwithend_userandstanding: suspendedsuspends the user and ends their sessions. It returns the identifier, the suspended standing, andsessions_ended. Within sixty seconds, the headerx-turnzero-cloud-sessionhas the valueinvalidon the ended sessions' requests. A backend's cached result from the verification route can stay valid until its cache time ends.tzcloud_set_end_user_standingwithend_userandstanding: activerestores active standing so the user can sign in again. Ended sessions stay ended.tzcloud_delete_end_userwithend_userneeds the browser approval described in The pending action. It removes the user's identities, sessions, passkeys, and record, and returnsdeletedand the removal counts. The realm's event and usage records remain.tzcloud_revoke_app_sign_in_keyswithenvironment, which it requires, revokes every signing key of the realm, for a suspected key compromise. Every user of the realm signs in again. It returnsrevoked, the revoked key identifiers, andkeys_changed_at, which isnullfor a realm no one has signed in to yet.
Verifying an end user describes how a revocation and a key rotation reach the routers.
4. Configure the realm #
Call tzcloud_configure_app_sign_in with the settings to change. Options you leave out keep their values, and a change takes effect at once, with no redeploy. tzcloud_read_app_sign_in returns the realm's settings, the declared native clients with each one's versions_seen from the last day, user and session counts, and the names of its secrets, never their values. Where the audience narrows the sign-in methods the realm offers, its detail says so. Without application, tzcloud_configure_app_sign_in, tzcloud_invite_end_user, and tzcloud_list_invitations address the platform's own accounts, which only platform staff may change. A call from you in that form is refused grant_required.
The recorded manifest controls each field its realm member names. tzcloud_configure_app_sign_in refuses a call that would change one, manifest_owned_field; a call that repeats the recorded value passes. The member's clients names one list per environment, and the manifest controls each list only in that environment. To let tzcloud_configure_app_sign_in change a field again, remove it from the manifest and submit the manifest again. Configure sign-in and push in the manifest shows the member.
| Field | Owner | What it sets |
|---|---|---|
sign_in_methods |
The manifest, while its realm member names the field, for every realm at each submission. Otherwise tzcloud_configure_app_sign_in, on one realm per call. |
The complete list of sign-in methods, replacing the current one: any of google, github, passkey, email, entra, and apple. An empty list turns sign-in off, and passkey is accepted only beside email (Add sign-in to your app). |
creation |
As for sign_in_methods. |
open or invited (Make sign-up invitation-only). |
entra |
As for sign_in_methods. |
The work-account route's tenant, client identifier, and client secret's name (Add work-account or Apple sign-in). |
apple |
As for sign_in_methods. |
Sign in with Apple's Services ID, team, key, and signing key's name (Add work-account or Apple sign-in). |
limits.creation_ceiling |
tzcloud_configure_app_sign_in alone, for each environment. |
The most users the realm will create, a positive integer; 1,000 by default. |
limits.signin_starts_per_hour |
tzcloud_configure_app_sign_in alone, for each environment. |
Sign-in starts allowed from one source address per hour, a positive integer; 30 by default. An IPv6 address counts as its /64 network. An emailed-code start and a passkey sign-in each count as one start. |
limits.code_sends_per_hour |
tzcloud_configure_app_sign_in alone, for each environment. |
Emailed codes sent to one address per hour; 5 by default, 30 at most. |
invitation_days |
tzcloud_configure_app_sign_in alone, for each environment. |
Days an invitation lasts, a positive integer; 14 by default. It applies to invitations issued after the call. |
session_days |
tzcloud_configure_app_sign_in alone, for each environment. |
Days an end-user session lasts, from 1 to 30; 30 by default. Sessions opened after the call use the new value, and open sessions keep their expiry. A native app's session is extended by this many days at each refresh. |
session_cap_days |
tzcloud_configure_app_sign_in alone, for each environment. |
The most days a native app's session may run from its creation, from session_days to 730; 365 by default, checked at each refresh. |
clients |
The manifest replaces each environment's clients list at once at each submission. On development, tzcloud_create_environment applies the list when it adds the realm. Where the manifest omits the list, call tzcloud_configure_app_sign_in for one realm at a time. |
Up to ten native apps can sign in through the realm. Each client has a client_id and redirect_uris (Declare the client on each environment's realm). For a list in the manifest, send all listed clients with their manifest fields, in any order. The call changes only minimum_version and update_url. Resubmitting the manifest keeps those values. Omitting them from the call clears them. See Keep installed clients compatible. |
Under the workforce audience, only the declared tenant's staff may sign in. Leave creation at open, its default: each staff member's first sign-in creates their end user without an invitation. tzcloud_configure_app_sign_in refuses creation: "invited" while the entra route stands, with invited_realm_refuses_work_account. The realm's limits.creation_ceiling still applies.
The limits on emailed codes #
| Limit | Value | Refusal |
|---|---|---|
| Codes sent to one address per hour | limits.code_sends_per_hour, 5 by default |
signin_code_rate_limited |
| Wrong entries for one address per hour | 10 | signin_code_rate_limited |
| Codes one realm sends per hour | 1,000 for either application size | signin_code_rate_limited |
| Codes sent across the platform per hour | The platform's mail quota less 20; 80 at the default quota | signin_code_rate_limited |
| Emailed-code starts from one source address per hour, across every realm | A sixth of the platform-wide limit; 13 at the default quota | signin_rate_limited |
Only limits.code_sends_per_hour can be raised, up to 30. A code start also counts toward the realm's signin_starts_per_hour, which does not change that share. The code message is fixed text: the code, its ten-minute validity, a line for anyone who did not ask, and a line saying never to share the code. Its subject's hostname label is the application's label for production, <label>-dev for development, and the new label after a rename.
Each environment's realm #
The application has one end-user realm for each environment: production's alone on an application with one environment, where testers and live users sign in alike. A development realm can have at most ten end users, on either size. A sign-in that would create an eleventh is refused 403 development_realm_full, and an existing user can always sign in. Test end users count toward neither this limit nor creation_ceiling. tzcloud_list_end_users marks each with test: true, and tzcloud_read_app_sign_in counts them as counts.test_users.
For more than ten human testers, use production's realm, which has no development-realm limit. No setting you can change raises development's ten-user limit. Those testers become production end users, as step 2 explains.
Deleting the application deletes every realm it has. tzcloud_delete_environment deletes the development realm alone, with its users, passkeys, and invitations, and leaves the application with one environment. The next tzcloud_create_environment creates a new development realm with the default sign-in methods, google, github, email, and passkey, and open creation, then applies the manifest's realm member where there is one. Under an invited audience it is invitation-only instead. If the old realm had other settings the manifest does not name, configure them again with tzcloud_configure_app_sign_in.
5. Passkeys for your users #
A passkey lets a user who signs in by emailed code sign in faster, so a realm offers passkey only beside email. Where it offers both, a user with no passkey is offered one after each sign-in by emailed code, and never after a Google or GitHub sign-in. A user who declines is offered one again after thirty days. Leaving passkey out of sign_in_methods turns off both that offer and passkey sign-in.
To remove email from sign_in_methods that lists passkey, remove passkey with it. The realm keeps its users' passkeys, unused, until both routes return. A realm whose stored sign-in methods list passkey without email serves no passkey route, and the detail of tzcloud_read_app_sign_in says so.
Only a user who holds the emailed code can register a passkey. GET /__account/passkeys returns levers, the routes the user signs in with, so your page shows a passkey control only where levers includes email. It also returns passkey_registration, whose admitted is true where the user can register one and otherwise false, beside a remedy that tells the user how to add sign-in by emailed code. For any other user the register routes return 409 passkey_requires_email. To add sign-in by emailed code, the user signs in by code once at the address their Google or GitHub sign-in verified.
A passkey works only on the hostname it was registered on, so a development passkey works only on the development hostname. Renaming the application changes its hostnames, so a passkey registered before the rename stops working. The person signs in another way and registers a new passkey. The old one is then called stranded:
GET /__account/passkeys, under the person's session, lists it understranded, apart from thepasskeysthat still work.POST /__account/passkeys/remove-strandedwith itscredential_idremoves it under that session, with no passkey prompt. It returns the remaining lists.- A passkey that still works is refused there with 409
passkey_not_stranded. Remove it the ordinary way, which asks for the passkey.
A domain of your own moves production's sign-in to it: once it serves, passkeys registered on the managed production hostname stop working until you detach it (What changes for your users).
POST /__account/passkeys/remove-lost with its credential_id removes a passkey the person deleted from their device. It needs a session that signed in again in the last five minutes, as does registering a passkey outside the offer after a sign-in by emailed code. To sign in again from a live session, the person uses any of these routes:
GET /__account/start/<provider>?intent=reauth&return=app, which shows the provider's account picker and must return the same account; Sign in with Apple shows its own confirmation sheet instead, which counts the same;- a POST of
intent=reauthandreturn=appto/__account/email/start, which emails a code to the person's own verified address; POST /__account/passkeys/reauth/options, thenPOST /__account/passkeys/reauth, which confirms the person with another of their passkeys.
Where the person's verified address is at a domain that no longer publishes a mail server, that POST is refused email_domain_undeliverable on a page offering their provider and passkey routes instead.
The provider and emailed-code routes return to your application's root. A POST that sends the session cookie must come from your application's own origin. Your backend presents the session as a bearer token instead.
A passkey change can be undone for three days. GET /__account/passkeys lists each open change under revertible, and POST /__account/passkeys/revert with its change_id, under the same fresh sign-in, undoes it. The undo signs out the user's other sessions and opens the caller's session again.
After a passkey sign-in, the application's sign-in page tells the user's passkey provider which of their passkeys still work, counting a passkey whose removal can be undone until its three days end. Where a user picks a passkey the realm does not have and cannot restore, the page tells the provider it is unknown, and a provider that supports these signals can hide or delete it.
Passkey notices #
When a user registers or removes a passkey, the platform emails a notice from donotreply@turnzero.ai to every address the user's identities have verified. The subject includes the hostname label, as the emailed-code message does. The notice says what changed and when. It says nothing is needed if the user made the change, and otherwise to sign in and review their passkeys. It contains no link and nothing the user typed. A user with no verified address is sent nothing.
The platform removes a passkey whose user holds no emailed-code sign-in, at the latest the next time it is used, and announces and records that removal the same way.
Notices have their own limits, which you cannot change and which do not count toward the limits on emailed codes:
- at most five notice messages an hour across the platform, and two notices an hour for one user or account;
- a notice past the limit is queued and sent later, with several changes combined into one message;
- a notice still queued after seven days is dropped.
The change is recorded in the realm's event log either way.
6. Verify a session from the backend #
Your backend tells which user sent a request with the Account package's verification client, as Tell which user sent a request shows.
Expected result #
tzcloud_invite_end_user with email returns the invitation's id, email, single-use url, and expires_at, and its detail says nothing was emailed. After the person uses the URL, tzcloud_list_end_users lists them with standing: "active" and the route they used. tzcloud_list_invitations shows the row as redeemed, with redeemed_by identifying that user.
tzcloud_set_end_user_standing returns standing: "suspended" and sessions_ended for a suspension, and standing: "active" for a reinstatement. tzcloud_revoke_app_sign_in_keys returns the revoked key identifiers and keys_changed_at. tzcloud_delete_end_user returns a pending action with its approval link, and after you approve, read_approval_status shows deleted: true with the removal counts.
tzcloud_configure_app_sign_in returns a realm object with the realm identifier, the sign_in_methods, the creation policy, the three limits, invitation_days, session_days, and the entra and apple settings where they are set. It also returns callbacks, the platform's addresses that the entra registration and the apple Services ID list. Its detail says the realm uses the configuration from now on.
The realm keeps this configuration until a tzcloud_configure_app_sign_in call or an accepted tzcloud_submit_manifest changes it. The manifest changes only fields its realm member names. Deploying code changes none of it.
tzcloud_read_app_sign_in returns the same realm object with the declared clients' versions_seen, the counts, and the secrets names, beside callbacks. Its page is the address of this page. Under the invited audience, its detail says creation is invitation-only whatever the configured mode, and Make sign-up invitation-only says what a sign-in without an invitation gets.
Refusals #
See the refusals reference for other platform errors.
A refusal identifies the action, states the cause in its detail, and changes nothing. The management actions return the rows down to manifest_owned_field. The routes under /__account/ and the verification route return the rows after it. Add sign-in to your app lists the sign-in pages' other refusals, and Add work-account or Apple sign-in those of a stored client secret or signing key.
| Refusal | Status | Cause | Remedy |
|---|---|---|---|
invalid_request |
400 | A member is missing or malformed, such as an unknown route, limits.code_sends_per_hour over 30, or a stale cursor. The detail names it. |
Correct the named member and call again. For a stale cursor, start again from the first page. |
no_such_application |
404 | application is not one of the account's applications. |
Use the identifier tzcloud_list_applications returns. |
application_other_account |
403 | application names an application that another account holds, not the account the call is signed in as. The detail names the account the call acted as and nothing of the other one. |
Compare turnzero whoami with read_account over your AI tool's connection. Make the call from the one signed in to the account that holds the application. |
realm_not_declared |
404 | The manifest declares no accounts service, so the environment has no realm. | Declare {"kind": "accounts"} in the manifest, resubmit it with tzcloud_submit_manifest, and call again. |
environment_not_created |
409 | A realm action named development on an application with one environment, which has no development realm. A call to the verification route under a minted token or an account-wide credential that names development is refused the same way. |
Pass production, or leave environment out. To give development a realm of its own, call tzcloud_create_environment. |
no_such_end_user |
404 | end_user matches no user in that application's realm for that environment. |
Use an identifier from tzcloud_list_end_users for the same environment. |
not_found |
404 | tzcloud_invite_end_user named in invitation an identifier the realm does not have. |
Use an identifier returned by tzcloud_invite_end_user with email, or by tzcloud_list_invitations, for the same realm. |
grant_required |
403 | tzcloud_configure_app_sign_in or an invitation action was called without application. |
Name an application of your account. |
token_scope_refused |
403 | A token bound to one application named another application, or left out application. |
Use a token for this application or for the whole account, and name the application. |
manifest_owned_field |
409 | tzcloud_configure_app_sign_in would change a field the recorded manifest's realm member names (Configure the realm). On an environment whose clients the manifest lists, it would add, remove, or change a client beyond its minimum_version and update_url. The detail names each field and client. |
Change the field in the manifest and submit it with tzcloud_submit_manifest. Or remove the field from the manifest's realm member and submit it, after which tzcloud_configure_app_sign_in changes it. A client's minimum_version and update_url stay with tzcloud_configure_app_sign_in: to change only those, send each listed client's other members as the manifest lists them. |
realm_creation_ceiling |
403 | A sign-in would create more users than creation_ceiling, 1,000 by default. |
Raise limits.creation_ceiling with tzcloud_configure_app_sign_in, or delete users. |
user_suspended |
403 | A suspended user signed in. | Restore the user by calling tzcloud_set_end_user_standing with standing: active. |
passkey_requires_email |
409 | A passkey registration, at /__account/passkeys/register/options or /__account/passkeys/register, named a user who holds no emailed-code sign-in. |
The user signs in by code once at the address their Google or GitHub sign-in verified, which adds the code to their account, and then registers the passkey. |
key_revoked |
401 | The session's token was signed by a key tzcloud_revoke_app_sign_in_keys revoked; the verification route returns session_revoked. |
The person signs in again. |
signin_rate_limited |
429 | A source address passed signin_starts_per_hour, or its share of emailed-code starts in the hour across the platform. Or the address's passkey autofill requests on an application's sign-in page passed 120 in the hour, a window of its own that counts no sign-in start. The detail gives the share's number. |
Wait for the hour to pass. Raise the first limit with limits.signin_starts_per_hour; the share cannot be raised. |
invalid_request |
400 | A request on the sign-in path, or to the verification route, contained a NUL character (U+0000) or an unpaired UTF-16 surrogate. Its detail, or the page a browser is shown, identifies the character rather than a member. |
Send the request again without the character. |
Related #
- Add sign-in to your app turns sign-in on, chooses the sign-in methods, and tells your backend which user sent a request.
- Make sign-up invitation-only limits sign-up to the people you invite.
- Add work-account or Apple sign-in adds a company's work accounts or Sign in with Apple.
- Test sign-in with test end users creates end users your AI tool signs in with no mailbox, and removes them.
- Verifying an end user explains the session token and how a revocation reaches the routers.
- What happens without asking explains the pending action
tzcloud_delete_end_usercreates. - tzcloud_configure_app_sign_in, tzcloud_read_app_sign_in, tzcloud_list_end_users, tzcloud_invite_end_user, tzcloud_list_invitations, tzcloud_set_end_user_standing, tzcloud_delete_end_user, and tzcloud_revoke_app_sign_in_keys in the generated reference give each action's arguments and result.