Concepts
Workspace
Section titled “Workspace”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.
App group
Section titled “App group”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.
Environment
Section titled “Environment”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.
Issuer host
Section titled “Issuer host”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.
Client
Section titled “Client”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.
Session
Section titled “Session”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.
Tokens
Section titled “Tokens”| 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.