Environments
Each app group has two environments, development and production. An environment has its own users, sessions, login methods, security policy, providers and signing keys; its id is in every app and group object (environments[].id). Environments are made with their group and cannot be created on their own.
The environment
Section titled “The environment”Read an environment
Section titled “Read an environment”| Field | Type | Meaning |
|---|---|---|
id |
uuid | |
group |
object | { id, slug, name } |
environment |
string | development or production. |
host, issuer |
string | Where the environment is served, and its issuer URL. |
signup_mode |
string | open, invite_only or closed. |
mfa_policy |
string | optional or required. |
refuse_email_tags |
boolean | Refuse addresses with a +tag for new accounts and new addresses. |
refuse_disposable_emails |
boolean | Refuse addresses at throwaway email services. |
one_account_per_gmail_inbox |
boolean | Treat every spelling of a Gmail inbox as the same address. |
captcha_every_signup |
boolean | Ask a captcha of every sign-up in this environment. |
login_methods |
string[] | The enabled methods, from the catalogue. |
theme |
object | The environment’s appearance. |
passkey_rp_id |
string or null | The passkey domain. |
captcha_enabled |
boolean | Read-only: whether the service has a captcha at all. Without one, nothing is asked. |
plan |
object | Read-only: { id, name, captcha_every_signup, retention_days } of the workspace’s plan. captcha_every_signup: true means the plan asks a captcha of every sign-up whatever the environment says. |
signups_today |
object or null | Read-only: on a plan with a daily cap, { made, limit, paused, resumes_at }; null otherwise. |
apps[] |
array | { id, slug, name, access_mode, theme, terms_url, email_required } for each app of the group. |
A new environment starts with signup_mode: "open", mfa_policy: "optional", login_methods: ["email_code"], an empty theme and every switch off, except refuse_disposable_emails, which is on from the start on a plan that refuses throwaway addresses (Free). The token and session lifetimes are a route of their own.
Change the security policy
Section titled “Change the security policy”Every field is optional; one that is left out keeps its value. The answer is the whole environment.
| Field | Type | Meaning |
|---|---|---|
signup_mode |
string | open, invite_only or closed. |
mfa_policy |
string | optional or required. Passwords are at least 15 characters under optional and at least 8 under required, at most 64 in both. |
refuse_email_tags |
boolean | |
refuse_disposable_emails |
boolean | |
one_account_per_gmail_inbox |
boolean | |
captcha_every_signup |
boolean | |
passkey_rp_id |
string or null | The passkey domain. null removes it. |
The passkey domain is trimmed, lowercased and loses a trailing dot. It must be a domain name: two or more labels, each 1 to 63 letters, digits and hyphens without a hyphen at either end, 253 characters in all, and a last label that is not only digits. localhost is allowed in a development environment only. It must be your app’s own domain or the environment’s login address: the platform’s domain, or a domain above it, is refused. See Passkeys.
PATCH /v1/environments/{env}{ "mfa_policy": "required", "signup_mode": "closed", "passkey_rp_id": " Example.COM. " }saves "passkey_rp_id": "example.com".
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
“signup_mode must be open, invite_only or closed”, “mfa_policy must be optional or required”, “the passkey domain is a domain name such as example.com”, “the passkey domain is your app’s own domain, or this environment’s login address” |
| 409 | conflict |
“turn the passkey login method off before removing its domain” |
There is no password policy beyond the lengths above. See Bot protection and Sign-ups and access for what the switches do.
Read the overview
Section titled “Read the overview”The environment’s headline numbers, kept for a minute.
{ "users": 42, "mau": 17, "plan": { "id": "free", "name": "Free" }, "signups_today": { "made": 3, "limit": 100, "paused": false, "resumes_at": "…" }, "last_7_days": { "logins_succeeded": 120, "logins_failed": 4, "mfa_failed": 1, "refresh_reuse_detected": 0 }, "recent_logins": [{ "occurred_at": "…", "user_id": "…", "ip": "…", "amr": ["email"], "client_id": "your-app-spa" }]}users counts everyone in the environment, mau the active users of the current month, and recent_logins holds the last 10 successful logins.
Login methods
Section titled “Login methods”List login methods
Section titled “List login methods”{ "methods": [...] }, each { id, label, enabled, available, social, custom, has_credentials, uses_shared_credentials }. The built-in catalogue, in order:
id |
Method | Social | Available |
|---|---|---|---|
email_code |
Email codes | no | yes |
password |
Passwords | no | yes |
passkey |
Passkeys | no | yes |
google |
yes | yes | |
apple |
Apple | yes | yes |
github |
GitHub | yes | yes |
discord |
Discord | yes | yes |
x |
X | yes | yes |
microsoft |
Microsoft | yes | yes |
phone |
Phone codes | no | no |
solana |
Solana wallets | no | yes |
evm |
EVM wallets | no | yes |
The environment’s custom providers follow, with custom: true. In a development environment, a social provider without credentials of its own uses the platform’s shared ones (uses_shared_credentials).
Choose the login methods
Section titled “Choose the login methods”| Field | Type | Meaning |
|---|---|---|
methods |
string[] | The complete set of enabled methods: built-in ids and custom-… ids. |
PUT /v1/environments/{env}/login-methods{ "methods": ["password", "email_code"] }The set is saved in catalogue order without repeats, so this answers "login_methods": ["email_code", "password"] in the environment.
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
“{label} is not available yet” (phone), “Passkeys need a passkey domain first: the domain your app runs on”, “{label} needs your own OAuth credentials in this environment” (a social provider with no credentials here; in development the platform’s shared ones count), “unknown login method {id}”, “at least one login method must stay enabled” |
Providers
Section titled “Providers”Social providers and your own OpenID Connect or OAuth 2 providers. A provider’s credentials are stored encrypted and never read back. See Social and custom providers.
List providers
Section titled “List providers”The providers set up in this environment, each with provider, kind (oidc or oauth2), client_id, email_trusted, custom and callback_url, the address to register at the provider: https://your-app.auth.dev.seek.services/callback/{provider}. Apple adds team_id and key_id. A custom provider adds label and what it was set up with: issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, scopes, claims, token_auth. No secret is ever listed.
Set up a provider
Section titled “Set up a provider”:provider is a built-in id (google, apple, github, discord, x, microsoft) or a custom id: custom- followed by 2 to 32 lowercase letters, digits or hyphens, not starting or ending with a hyphen. Setting a provider up does not enable it: add it to the login methods as well.
| Field | For | Meaning |
|---|---|---|
client_id |
all | Required, up to 300 characters. |
client_secret |
all | Up to 5000 characters. Required the first time; leave it out to keep the stored one. For Apple, the text of the .p8 key. |
team_id, key_id |
Apple | Required, up to 20 letters and digits each. |
label |
custom | Required: the button’s text, 1 to 40 characters. |
kind |
custom | oidc (from the issuer’s discovery document) or oauth2 (endpoints named one by one). It cannot change later. |
issuer |
custom oidc |
The issuer URL, up to 500 characters. |
authorization_endpoint, token_endpoint, userinfo_endpoint |
custom oauth2 |
Up to 500 characters each. |
scopes |
custom | Up to 20, each up to 100 characters. |
claims |
custom oauth2 |
Where the profile’s values are: a map whose keys may be sub, email, email_verified, name and picture. |
token_auth |
custom | How the client authenticates at the token endpoint: basic (default) or post. |
email_trusted |
custom | Whether the provider’s verified address may link to, and create, an account with that address. Defaults to false, and is set on every save: send it each time to keep it on. |
Every endpoint must be an https address with a public host name. Google and Apple are trusted for email; the other built-in providers are not.
PUT /v1/environments/{env}/providers/custom-acme{ "label": "Acme SSO", "kind": "oidc", "issuer": "https://sso.acme.example", "client_id": "acme-client", "client_secret": "…", "scopes": ["email", "profile"]}answers the provider with "custom": true and "callback_url": "https://your-app.auth.dev.seek.services/callback/custom-acme".
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
“this provider is not available”, “client_id is required”, “client_secret is required”, “{key} is required” (Apple), “the key is not a P-256 private key in PEM, as in the .p8 file Apple gives out”, “label is required”, “kind is oidc or oauth2”, “scopes are not valid”, “claims.{claim} is not a claim this service reads”, “token_auth is basic or post”, “{name} must be an https address with a public host name”, “client_secret is required when the provider’s endpoints change”, or a custom id that does not follow the rule |
| 402 | plan_limit |
Custom providers are not in the workspace’s plan (Free). |
| 409 | conflict |
“an environment has at most 10 custom providers”, “a custom provider keeps its kind; remove it and add it again to change that” |
| 422 | invalid_entity |
A field over its length. |
Remove a provider
Section titled “Remove a provider”Answers 204, or 404. The provider also leaves the login methods, unless a development environment still has the platform’s shared credentials for it. Removing the only enabled login method answers 409 “this is the only enabled login method”.
Appearance
Section titled “Appearance”Set the appearance
Section titled “Set the appearance”The body is the theme itself, and it replaces the stored one. It applies to every app of the group that has no theme of its own. See Branding.
| Key | Values |
|---|---|
colors |
primary, background, text: hex #rgb, #rrggbb or #rrggbbaa, saved lowercased. |
radius |
none, sm, md, lg or full. |
font |
A font family name: up to 60 letters, digits, spaces, _ and -. |
logo_url |
An https URL, up to 500 characters. |
copy |
title and subtitle, up to 140 characters each, read as names are: one that passes for one of SeekAuth’s own products is 400 name_not_allowed. A line that is saved already stays when sent again. |
PUT /v1/environments/{env}/appearance{ "colors": { "primary": "#0EA5E9" }, "radius": "lg", "font": "Inter", "logo_url": "https://cdn.example/logo.svg", "copy": { "title": "Welcome back" }}A wrong value answers 400 with a message that starts theme:, such as “theme: colors are hex values like #1f2937” or “theme: unknown setting”. The answer is the environment.
Per-app settings
Section titled “Per-app settings”Read an app’s settings
Section titled “Read an app’s settings”The app’s entry (id, slug, name, access_mode, theme, terms_url, email_required) plus effective_theme: the app’s own theme when it has one, else the environment’s.
Change an app’s settings
Section titled “Change an app’s settings”Every field is optional; one that is left out keeps its value.
| Field | Type | Meaning |
|---|---|---|
access_mode |
string | open, invite_only or closed. |
theme |
object | The app’s own theme, with the keys above. |
terms_url |
string or null | An https URL of the app’s terms, which users accept once per app. null removes it. |
email_required |
boolean | Ask a user who has no email address for one before the login completes. |
Letting more people in takes the admin role: a more open access_mode (closed, then invite_only, then open) or turning email_required off answers 403 to a developer. Narrowing is a developer’s. See Sign-ups and access.
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
“access_mode must be open, invite_only or closed”, “terms_url is an https URL”, or a theme error |
| 403 | forbidden |
Widening access below the admin role. |
| 404 | not_found |
The app is not in this environment’s group. |
Signing keys
Section titled “Signing keys”Rotate the signing keys
Section titled “Rotate the signing keys”Keys rotate on their own every 90 days. This starts a rotation now: for ES256 and for RS256, a new key is published and starts signing 24 hours later, so that everyone who caches the key set has it first. If a new key is already waiting, the schedule decides instead. The answer lists the keys:
{ "keys": [ { "kid": "…", "alg": "ES256", "state": "active", "created_at": "…", "activated_at": "…", "retired_at": null }, { "kid": "…", "alg": "ES256", "state": "next", "created_at": "…", "activated_at": null, "retired_at": null } ]}state is next, active or retired. There is no route that only lists keys: the public keys are at the issuer’s /jwks.json. See Keys and secrets.