Skip to content

Concepts

Workspace, app group, environments and appsA workspace has members, a plan and API keys, and owns app groups. An app group, here with the slug shop, owns two environments: production at shop.auth.dev.seek.services and development at shop-dev.auth.dev.seek.services. Each environment has its own users, sessions, login methods, security policy and signing keys. The group also owns its apps, here Storefront and Back office, which share the environments' users. Each app has its own name, look, access rule, terms, clients, APIs and roles.Workspacemembers and their roles · plan · API keysApp groupslug shop · one set of users per environment, shared by its appsProductionshop.auth.dev.seek.servicesusers · sessions · login methodssecurity policy · signing keysDevelopmentshop-dev.auth.dev.seek.servicesusers · sessions · login methodssecurity policy · signing keysApp: Storefrontname · look · who may enter · termsclients · APIs · rolesApp: Back officename · look · who may enter · termsclients · APIs · roles
One workspace, one app group with two apps. Both apps log users in on the group's issuer hosts, and share its users.

A workspace is your team’s account. It has members, each with a role (viewer, developer, admin or owner), a plan with its limits, and API keys for the management API. People join a workspace only by accepting an invitation, and an owner can delete it, with everything in it, on its Settings page. See Workspaces and members.

An app group is a set of apps that share their users. It owns:

  • two environments, production and development;
  • in each environment, the users, their identities and second factors, their sessions, the enabled login methods, the security policy, the signing keys and the issuer host.

Creating an app on its own creates a group of one, with the app’s name and slug; most workspaces never need more. Add apps to the group when they should share accounts. See Apps that share accounts.

An app belongs to one group. It owns what its users see and what its servers trust:

  • its name, shown in the login and in the emails its users get, and its look (Appearance);
  • who may enter (its access mode: open, invite only or closed), its terms, and whether it needs an email address for each user;
  • its clients, APIs and roles.

Every group has a production and a development environment, and they share nothing: each has its own users, keys, sessions and settings. Development accepts http://localhost pages without registering them, lets the built-in social providers run on shared credentials, and is not counted against the plan’s monthly active users. See Going to production.

Each environment is served on its own host, which is its OpenID Connect issuer. It follows from the group’s slug:

Environment Issuer
Production https://shop.auth.dev.seek.services
Development https://shop-dev.auth.dev.seek.services

Every endpoint of the environment is on that host: discovery, /authorize, /token, the keys, the account API. The host is the only thing that selects the environment. On a paid plan an environment can move to a custom domain, such as id.shop.com, which then becomes its issuer.

A client is one piece of software that logs users in, or gets tokens of its own, through an environment. Its type decides how it authenticates:

Type Is Authenticates
spa A single-page app in the browser. Its tokens are bound to a DPoP key in the browser. No secret (PKCE and DPoP).
web A backend that logs users in and keeps their tokens. A client secret (HTTP Basic).
native A mobile or desktop app. No secret (PKCE and DPoP).
machine A job or service with no user, using client credentials. A client secret (HTTP Basic).

Each new app’s development environment comes with an SPA client, {slug}-dev-spa, ready to use from any http://localhost port. See Clients.

An API is a server of yours that takes access tokens. It has an audience, the value of the token’s aud (such as orders-api), and permissions (such as orders:write). A token is for exactly one API. Every environment also has the built-in account API (audience account), which lets a signed-in user manage their own account. See Calling your API.

A role is a named set of permissions, given to users (and to machine clients). A role belongs to one app, or to the whole group. A role can require two-step login: it then counts only in a session that passed two steps. See Roles and permissions.

A user is a person’s account in one environment of one group. They can log in to every app of the group that lets them in, with any login method linked to the account. A user’s sub is stable within that environment. Each user has an active or disabled status, and for each app that is not open, a standing: granted, active once they have entered, or disabled.

A session is one login on one device. It is made when someone proves who they are, used again whenever an app renews its tokens, and ends when it is revoked, when nobody used it for the inactivity timeout (30 days out of the box), or at its maximum length (90 days). See Sessions and sign-out.

Token Is Lasts (default)
Access token An ES256 JWT for one API, with the user’s roles and that API’s permissions. Your API verifies it offline. 5 minutes
ID token A JWT for the client, with who the user is. 5 minutes
Refresh token An opaque value that renews the other two. Each one works once. 30 days unused, never past the session

Each environment sets its own lifetimes. See Tokens and claims.