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 |
List clients
Section titled “List clients”{ "clients": [...] }, oldest first. ?app_id= keeps one app’s. No secret is listed. There is no route that reads one client on its own.
Create a client
Section titled “Create a client”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):
httpswith a host, no fragment, no*, up to 500 characters.http://localhost,http://127.0.0.1andhttp://[::1]with a port are taken in a development environment or for anativeclient;http://names underlocalhostin a development environment only. Anativeclient may also use a private-use scheme that contains a dot, such ascom.example.app:/callback. A development environment also accepts anyhttp://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 alocalhostorigin in development. - Machine clients have no redirect URIs and no origins: nobody logs in through them. Their
default_api_idmust 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. |
Change a client
Section titled “Change a client”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.
Rotate a client secret
Section titled “Rotate a client secret”{ "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 a client
Section titled “Delete a client”Answers 204, or 404. Its codes and refresh tokens go with it.
A machine client’s roles
Section titled “A machine client’s roles”A machine client gets roles of its own; its tokens carry their permissions. Users carry theirs instead (see Users).
Read a client’s roles
Section titled “Read a client’s roles”Set a client’s roles
Section titled “Set a client’s roles”| 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) |
Other apps’ APIs
Section titled “Other apps’ APIs”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.
Read a client’s other APIs
Section titled “Read a client’s other APIs”Set a client’s other APIs
Section titled “Set a client’s other APIs”| 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. |