Skip to content

Clients

A client is one way into an app: a browser app, a backend, a native app or a machine. Each belongs to one app and one environment. A spa or native client keeps its tokens on the device and has no secret; a web client is a backend that keeps a secret and the tokens; a machine client gets tokens for itself, with no user.

The client object:

Field Type Meaning
id uuid The record’s id, used in the paths below as :client.
app_id uuid The app it belongs to.
client_id string What the client sends as client_id.
name string
type string web, spa, native or machine.
first_party boolean Always true for clients made here.
auth_method string How it authenticates at /token: client_secret_basic or none.
default_api_id uuid or null The API its tokens are for when a request names none. Without one, tokens are for the account API.
redirect_uris, post_logout_redirect_uris string[] Where a login and a logout may return to.
allowed_origins string[] Which web pages may call the issuer from a browser.
id_token_alg string ES256 or RS256.
created_at string
GET/v1/environments/:id/clientsviewer

{ "clients": [...] }, oldest first. ?app_id= keeps one app’s. No secret is listed. There is no route that reads one client on its own.

POST/v1/environments/:id/clientsadmin with addresses, else developer

Naming any redirect URI, post-logout redirect URI or origin takes the admin role; a client without them takes developer.

Field Type Meaning
name string Required, 1 to 80 characters. The login page says it, so it is read as an app’s name is: no control or invisible characters, and nothing that passes for one of SeekAuth’s own products (400 name_not_allowed).
type string Required: web, spa, native or machine.
app_id uuid The app. Optional when the group has one app.
client_id string Optional. 3 to 64 lowercase letters, digits and hyphens; not a UUID, not ending in -dev-spa, unique across the service. Made up when left out: {app slug}[-dev]-{type}-{6 hex digits}.
default_api_id uuid Optional: an API of the app.
redirect_uris string[] Default []. At most 50.
post_logout_redirect_uris string[] Default []. At most 50.
allowed_origins string[] Default []. At most 50.
id_token_alg string ES256 (default) or RS256.

The type decides how the client authenticates; there is no separate setting for it:

type auth_method Has a secret
web client_secret_basic yes
machine client_secret_basic yes
spa none no
native none no

Addresses must follow these rules:

  • Redirect URIs (both lists): https with a host, no fragment, no *, up to 500 characters. http://localhost, http://127.0.0.1 and http://[::1] with a port are taken in a development environment or for a native client; http:// names under localhost in a development environment only. A native client may also use a private-use scheme that contains a dot, such as com.example.app:/callback. A development environment also accepts any http://localhost:<port> redirect without registering it.
  • Origins: exactly an origin (https://app.example, with a port if there is one, and nothing after it). https, or a localhost origin in development.
  • Machine clients have no redirect URIs and no origins: nobody logs in through them. Their default_api_id must be one of their app’s own APIs, not the account API.
POST /v1/environments/{env}/clients
{
"name": "Web",
"type": "web",
"default_api_id": "…",
"redirect_uris": ["https://app.example/auth/callback"],
"allowed_origins": ["https://app.example"]
}
201
{
"id": "…",
"app_id": "…",
"client_id": "your-app-web-3f9a1c",
"name": "Web",
"type": "web",
"first_party": true,
"auth_method": "client_secret_basic",
"default_api_id": "…",
"redirect_uris": ["https://app.example/auth/callback"],
"post_logout_redirect_uris": [],
"allowed_origins": ["https://app.example"],
"id_token_alg": "ES256",
"created_at": "…",
"client_secret": "…"
}

client_secret is in this answer only, for web and machine clients. SeekAuth keeps its hash.

Status code When
400 bad_request “type must be web, spa, native or machine”, “device clients are not available yet”, “app_id is required: this group has several apps”, “app_id names no app of this environment’s group”, “client_id is 3 to 64 lowercase letters, digits and hyphens”, “client_id cannot be a UUID”, “client_id cannot end with -dev-spa, which provisioning reserves”, “{uri} is not an acceptable redirect URI here”, “{origin} is not an origin like https://app.example”, “a machine client has no redirect URIs and no origins: nobody logs in through it”, “id_token_alg must be ES256 or RS256”, “default_api_id names no API of this environment”, “default_api_id names an API of another app of the group”, “a machine client’s default API is one of its app’s APIs”, “a client names at most 50 redirect URIs, 50 post-logout redirect URIs and 50 origins”, “{host} is a store’s address. …” (the address of a Seek store, which only Seek’s own setup of the store’s customer accounts names)
400 name_not_allowed The client’s name passes for one of SeekAuth’s own products, or holds control or invisible characters.
403 forbidden Addresses named below the admin role.
409 conflict “this client_id is taken”
422 invalid_entity name missing or too long.
PATCH/v1/environments/:id/clients/:clientdeveloper; admin to change addresses

Changing any of the three address lists takes the admin role. The answer is the client. A list takes at most 50 addresses (one that holds more already keeps them and takes no more), and a new name is read as on creation; the name a client has stays.

In the workspace Seek made for your stores, a store’s own client keeps the store’s address: you can add another path on it or take one away, and you cannot add a store’s address to any client yourself. Seek adds it when the store’s customer accounts are turned on.

POST/v1/environments/:id/clients/:client/secretadmin
{ "client_secret": "…" }

The old secret stops working at once, so update the client’s configuration right after. A client without a secret (and an unknown client) answers 400 “only web and machine clients have a secret”.

DELETE/v1/environments/:id/clients/:clientdeveloper

Answers 204, or 404. Its codes and refresh tokens go with it.

A machine client gets roles of its own; its tokens carry their permissions. Users carry theirs instead (see Users).

GET/v1/environments/:id/clients/:client/rolesviewer
PUT/v1/environments/:id/clients/:client/rolesadmin
Field Type Meaning
role_ids uuid[] The complete set of roles, without repeats.
PUT /v1/environments/{env}/clients/{client}/roles
{ "role_ids": ["…"] }
200
{ "role_ids": ["…"] }

A role that requires two-step login is accepted but never counts for a client, which never logs in.

Status code When
400 bad_request “only a machine client has roles of its own; users carry theirs”, “role_ids names a role this environment does not have” (also for a repeated id)

A client may ask for tokens for its own app’s APIs and the account API. To call an API of another app of the same group, the client must be allowed it.

GET/v1/environments/:id/clients/:client/apisviewer
PUT/v1/environments/:id/clients/:client/apisdeveloper; admin to add
Field Type Meaning
api_ids uuid[] The complete list of other apps’ APIs this client may ask for. [] withdraws them all.
PUT /v1/environments/{env}/clients/{client}/apis
{ "api_ids": ["…"] }
200
{ "api_ids": ["…"] }

Adding an API takes the admin role; removing one does not. A token for another app’s API is issued only if that app lets the user in.

Status code When
400 bad_request “api_ids names no API of this environment”, “only APIs of other apps of the group need to be allowed” (the account API, or the client’s own app’s)
403 forbidden Adding below the admin role.