Skip to content

Apps and groups

An app group owns two environments, a development one and a production one, with their users, sessions, login methods and signing keys. An app belongs to one group and owns its name, look, access mode, clients, APIs and roles. An app created on its own gets a group of one that shares its name and slug.

A group’s slug names its environments’ hosts, which are their issuers:

Environment Host Issuer
Production {slug}.auth.dev.seek.services https://your-app.auth.dev.seek.services
Development {slug}-dev.auth.dev.seek.services https://your-app-dev.auth.dev.seek.services

A slug is 3 to 40 lowercase letters, digits and single hyphens, with no hyphen at either end. When none is given, it is made from the name: letters and digits are lowercased and every other run of characters becomes one hyphen, so Link Pay! becomes link-pay. Slugs are unique across the service.

These are reserved and answer 409 “this app slug is reserved”, as does any slug that ends in -dev:

api www docs status login signin dashboard console admin
account accounts sso support help billing security mail auth platform

So is a slug that reads as somebody else’s brand, since a login page on it would be shown under SeekAuth’s address: banks and payment companies, the platforms people log in with, crypto wallets and exchanges. Such a slug is refused when it is the brand (paypal, pay-pal) or the brand with nothing beside it but words a login, support or billing page would use, or a number (paypal-login, secure-stripe, apple-id, microsoft-365); a slug where the brand is one ordinary word among others is not (apple-orchard-farm, chase-bakery, zoom-photo-studio). Digits and letter pairs that pass for letters count as those letters (paypa1, rnicrosoft). The names of SeekAuth’s own products are held to more: refused alone (seek, seekgrow, grow), run together with such words or hosts’ words (seekid, myseek, seekpay, grow-login), and a long one anywhere in the slug (linkpay-pay); a word that only contains one, or one word among others, is not (seekers, hide-and-seek-toys, seek-pizza-shop, grow-garden).

A name people read (an app’s, which heads its login page and names it in the login codes SeekAuth emails, a group’s and a workspace’s) cannot pass for Seek, SeekAuth, LinkPay, SeekGrow or Seek Services: 400 with the code name_not_allowed. The same rule reads every other word of yours that a login page shows: a client’s name, the heading and the line under it (copy.title, copy.subtitle), and a custom provider’s button label and id. The rule:

  • How a name is read. It is cut into words, and a word into runs of one script; Latin and the scripts drawn like it (Greek, Cyrillic, Armenian, Georgian, Cherokee, Lisu and others) count as one script, while Chinese, Japanese, Korean, Arabic, Hebrew, Thai and the scripts of India are each their own. Every run is read through Unicode’s table of confusable characters, with accents, wide, styled, boxed and circled letters, digits and symbols that pass for letters, and letters spaced out counting as what they look like (S e e k, Seek, Ѕеек in Cyrillic, ꓢꓰꓰꓗ in Lisu, 🅢🅔🅔🅚, L!nkPay, $eek). A letter of a script of its own never stands in for a Latin letter it does not look like, and a Latin word written against Chinese, Japanese or Korean is read as if a space stood between them: Seek咖啡 is Seek 咖啡, and Ѕеек登录 is Ѕеек 登录.
  • SeekAuth, LinkPay, SeekGrow and Seek Services, which are no word of any language, are refused wherever a word, or a few words in a row, read as one of them, whatever stands next to it (LinkPay Ltd, Link Pay Toys, Seek Grow Farm, LinkPayments, MyLinkPay, LinkPayLogin, LinkPay™); a word that only contains one is not (BlinkPay, Link Payroll).
  • Seek, an everyday word, is refused as the whole name (Seek, The Seek, Welcome to Seek, Seeks); next to a word a login, support or payment page uses, before or after it, with at most one word between (Seek Login, Seek App Login, Seek My Account, Log in to Seek App, Support for Seek, Hide and Seek Team); run together with one (SeekLogin, LoginSeek, PaySeek); or when it is not written in its plain letters (Ѕееk Shop, S33k Shop, Séek Shop). Those words are known in English (login, sign in, account, ID, password, code, 2FA, support, help, customer service, security, verify, billing, pay, payout, bank, merchant, portal, dashboard, official, team, staff, admin and their plurals), in the languages of SeekAuth’s own products (Вход, Iniciar sesión, Σύνδεση, Pieslēgties, Prisijungti, Sisselogimine…) and in Chinese, Japanese and Korean for log in, sign up, account and support (Seek 登录, Seek ログイン, Seek 로그인).
  • A name made only of such words (Support, Security Team, No Reply, Admin, Login, Billing) is refused as the name of an app, a group or a workspace, which SeekAuth’s emails are sent in the name of. A heading, a line, a button’s label and a client’s name may say them (Sign in, Log in to your account).
  • Names that pass: an ordinary word next to Seek (Seek Shop, Hide and Seek Toys, Seek 咖啡, Seek서울, Now Seek, Go Seek, Myseek), ordinary words that contain a brand’s letters (Seekers Club, Payseeker, Grow Shop), and a name wholly in another script that does not read as one of these names.

Any name with characters nobody sees that can change it (a right-to-left override or embedding, a zero-width space, a byte order mark) is refused with the same code; the marks of writing direction that Hebrew and Arabic text carries (U+200E, U+200F, U+061C) are taken out of the name instead. This is checked when a name is given or changed; names from before stay, and sending an app’s current name again is accepted. name_not_allowed is about the name alone: a different slug will not help.

A slug a group gives up, by a change or by being deleted, stays held for its workspace: apps may still trust the issuer it named, so no other workspace may answer on it (409 “this address was used before and is not available”). The workspace that gave it up may take it again.

An environment can also be served on a custom domain instead of its platform host.

The app object:

Field Type Meaning
id, group_id uuid The app and its group.
slug, name string
created_at string
environments[] array { id, environment, host, issuer } for both environments.
development_client_id string Only in the answer that creates the app: the development SPA client made with it, {slug}-dev-spa.
POST/v1/workspaces/:id/appsdeveloper, not an API key

Creates an app in a new group of one, with both environments, their keys, and a development SPA client that accepts any http://localhost port.

Field Type Meaning
name string 1 to 80 characters, no control characters.
slug string Optional. Made from the name when left out.
POST /v1/workspaces/{ws}/apps
{ "name": "Your App" }
201
{
"id": "…",
"group_id": "…",
"slug": "your-app",
"name": "Your App",
"created_at": "…",
"environments": [
{ "id": "…", "environment": "development", "host": "your-app-dev.auth.dev.seek.services", "issuer": "https://your-app-dev.auth.dev.seek.services" },
{ "id": "…", "environment": "production", "host": "your-app.auth.dev.seek.services", "issuer": "https://your-app.auth.dev.seek.services" }
],
"development_client_id": "your-app-dev-spa"
}
Status code When
400 bad_request “an app slug is 3 to 40 lowercase letters, digits and single hyphens”
400 name_not_allowed The name passes for one of SeekAuth’s own products, is made only of words such as support or admin, or holds control or invisible characters: another slug will not help.
402 plan_limit The workspace has as many app groups as its plan includes, for example “The Free plan includes 1 app with accounts of its own. The Pro plan includes more.”
409 conflict “this app slug is reserved”, “this app slug is taken”, “this address was used before and is not available”
429 rate_limited More than 30 apps created in this workspace in an hour.
GET/v1/workspaces/:id/appsviewer

{ "apps": [...] }, each an app object without development_client_id.

GET/v1/apps/:idviewer
PATCH/v1/apps/:idadmin
Field Type Meaning
name string 1 to 80 characters after trimming.
slug string The new slug.
confirm string The group’s current slug, when the change moves the issuer.

Send a name, a slug, or both. When the app is alone in its group, the two share one name and one slug, and a new slug moves both environments to new hosts. That changes iss for every client, so confirm must repeat the current slug, or the answer is 400 “this changes the login address, which is the issuer of every client: repeat the current slug in confirm to go ahead”. In a group of several apps, an app’s slug is only its handle and needs no confirm.

PATCH /v1/apps/{id}
{ "name": "Shop", "slug": "shop", "confirm": "your-app" }
Status code When
400 bad_request “send a name, a slug, or both”, “a name is 1 to 80 characters”, or confirm missing
400 name_not_allowed The name passes for one of SeekAuth’s own products, is made only of words such as support or admin, or holds control or invisible characters.
409 conflict The slug is reserved, taken or held.

The answer is the app object.

DELETE/v1/apps/:idadmin

Answers 204. An app that is alone in its group cannot be deleted on its own (409 “this is the only app of its group: delete the group, which also deletes its users”); delete the group instead.

The group object:

{
"id": "…",
"slug": "your-app",
"name": "Your App",
"created_at": "…",
"apps": [{ "id": "…", "slug": "your-app", "name": "Your App", "created_at": "…" }],
"environments": [{ "id": "…", "environment": "production", "host": "…", "issuer": "…" }]
}
GET/v1/workspaces/:id/groupsviewer

{ "groups": [...] }, oldest first.

GET/v1/groups/:idviewer
PATCH/v1/groups/:idadmin

The same body as for an app: name, slug, and confirm with the current slug whenever the slug changes. A group of one renames its app too. An environment served on a custom domain stays there; only its platform host changes.

PATCH /v1/groups/{id}
{ "slug": "id-shop", "confirm": "shop" }
DELETE/v1/groups/:id?confirm=:slugowner

Deletes the group, its apps, and every user of both environments. The group’s slug must be repeated in the confirm query parameter, or the answer is 400 “deleting a group deletes its apps and every user in both environments: repeat its slug in confirm to go ahead”. Answers 204, and the slug is held for the workspace. The audit logs of both environments outlive them, and lose the address, user agent, device, browser and operating system of every event right after, in batches from a queue the deletion fills in its transaction; their mail queues and webhook deliveries go with them. The group that holds the developer accounts is refused 403, and the one that holds the accounts of Seek and LinkPay 409 conflict (as is every group while a deployment that names a suite cannot find it). See Data and retention. To delete every group at once, delete the workspace.

POST/v1/groups/:id/appsdeveloper, not an API key

Apps of one group share their users: someone who signs up in one has the same account in the others. The new app uses the group’s environments and keys.

Field Type Meaning
name string 1 to 80 characters.
slug string Optional: the app’s handle.
access_mode string open (default), invite_only or closed. See Sign-ups and access.

The answer is 201 with the app object, its access_mode and development_client_id; here production is listed first in environments.

Status code When
400 bad_request “access_mode must be open, invite_only or closed”
402 plan_limit The group has as many apps as the plan includes, for example 3 on Free.
429 rate_limited More than 30 apps created in this workspace in an hour.

Who may use an app follows from its access mode and each user’s standing in it. An app’s users are listed per environment.

GET/v1/environments/:id/apps/:app/usersviewer
Query Meaning
status granted (let in, not arrived yet), active or disabled.
after A user_id: the page after it.
limit 50 by default, at most 200.
{
"access_mode": "invite_only",
"users": [
{
"user_id": "…",
"email": "[email protected]",
"name": "Ada",
"status": "active",
"granted_at": "…",
"joined_at": "…",
"terms_accepted_at": "…",
"last_seen_at": "…"
}
],
"total": 1,
"next_after": null
}
POST/v1/environments/:id/apps/:app/usersadmin

Send exactly one of:

Field Type Meaning
user_ids uuid[] Up to 1000 users of the environment.
all true Every user of the environment.
from_app string Every user of another app of the group, by its slug or id.
POST /v1/environments/{env}/apps/{app}/users
{ "all": true }
200
{ "granted": 2, "skipped": 0 }

Users who already have a standing in the app, and ids nobody has, are skipped.

Status code When
400 bad_request “give exactly one of user_ids, all: true or from_app”, “name at most 1000 users in one request”, “from_app names no other app of this group”
409 conflict “this app is closed: it accepts no new grants”
PATCH/v1/environments/:id/apps/:app/users/:userdeveloper to disable, admin to enable
Field Type Meaning
status string disabled or active.

Disabling ends the user’s refresh tokens for this app only; their account and other apps are untouched. Enabling returns them to active if they had arrived, or granted if not. The answer is the user’s entry in the app.

DELETE/v1/environments/:id/apps/:app/users/:userdeveloper

Answers 204, or 404. The account itself stays; to delete it, see Users.