users

Download schema

User management (super-admin)

Get a user by id

GET

https://api.smach.science

/users/{id}

Get a user by id › path Parameters

id

string · required

Get a user by id › Responses

Unknown id

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

Update a user

PUT

https://api.smach.science

/users/{id}

Updates email, names, language, active state and the super-admin role; disabling (enabled=false) is the soft alternative to deletion. Fields left out are kept.

Update a user › path Parameters

id

string · required

Update a user › Request Body

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

Update a user › Responses

Unknown id

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

PUT/users/{id}

curl https://api.smach.science/users/:id \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}'

Example Request Body

{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}

json

Example Responses

{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}

json

application/json

Delete a user permanently

DELETE

https://api.smach.science

/users/{id}

Delete a user permanently › path Parameters

id

string · required

Delete a user permanently › Responses

User deleted

No data returned

List users

GET

https://api.smach.science

/users

Follow the Link header to page through the collection rather than building page URLs. The search parameter matches the username, the email and both names, anywhere in the field; a term carrying a * wildcard is passed through as written, so term* stays anchored at the start.

List users › query Parameters

page

integer · int32 · min: 0

0-indexed page number

Default: 0

size

integer · int32 · min: 1 · max: 200

Page size

Default: 50

search

string

Free-text search. The fields it matches are documented per endpoint.

sort

string

Sort field, prefixed with '-' for descending (e.g. -createdAt). Only present on endpoints whose backing store supports sorting.

List users › Responses

200

A page of results

User[]

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

Create a user

POST

https://api.smach.science

/users

Creates a user without credentials. Send the invitation next (POST /users/{id}/invitation): a failed email then leaves the user created, and the invitation alone is retried.

Create a user › Request Body

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

Create a user › Responses

User created

A platform user (backed by a Keycloak user; email is the username)

User

email

string · email · minLength: 1 · required

Email, also used as the username

id

string · readOnly

Keycloak identifier, server-assigned

firstName

string

Given name

lastName

string

Family name

enabled

boolean

Whether the account is active

emailVerified

boolean · readOnly

Whether the person confirmed the address; false while the invitation is pending

passwordSet

boolean · readOnly

Whether a password exists; only on the single-user read

locale

string · pattern: [a-z]{2,3}(-[A-Z]{2}…

Language of the emails and the login page

superAdmin

boolean

Whether the user holds the platform-wide super-admin role

organizations

string[] · readOnly

Aliases of the organizations the user belongs to

lastLogin

string · date-time · readOnly

Last login, absent when none is recorded: never logged in, older than the event retention (90 days), or login events not readable by the service

logins

integer · int32 · readOnly

Logins over the event retention (90 days), counted up to 1000; only on the single-user read, and absent when login events are not readable by the service

POST/users

curl https://api.smach.science/users \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}'

Example Request Body

{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}

json

Example Responses

{
  "id": "id",
  "email": "curator@bayeux.museum",
  "firstName": "Marie",
  "lastName": "Durand",
  "enabled": true,
  "emailVerified": true,
  "passwordSet": true,
  "locale": "fr",
  "superAdmin": false,
  "organizations": [
    "bayeux"
  ],
  "lastLogin": "2024-08-25T15:00:00Z",
  "logins": 0
}

json

application/json

Email a password reset link to a user

POST

https://api.smach.science

/users/{id}/password-reset

Keycloak emails a link where the person chooses a new password. The current password stays valid until then.

Email a password reset link to a user › path Parameters

id

string · required

Email a password reset link to a user › Responses

Email sent

No data returned

Email the invitation to a user

POST

https://api.smach.science

/users/{id}/invitation

Keycloak emails a link, valid three days, where the person chooses a password and confirms the address, then lands on SmaRT. Sending it again resends the invitation.

Email the invitation to a user › path Parameters

id

string · required

Email the invitation to a user › Responses

Email sent

No data returned

List the organizations a user belongs to, with their role in each

GET

https://api.smach.science

/users/{id}/organizations

List the organizations a user belongs to, with their role in each › path Parameters

id

string · required

List the organizations a user belongs to, with their role in each › Responses

Unknown id

OrganizationMembership[]

An organization a user belongs to, with their role in it

OrganizationMembership

alias

string

name

string

role

string | null · enum

Enum values:

administrator

viewer

Count users matching the filters

GET

https://api.smach.science

/users/count

Answers a business question; paging is driven by the list endpoint's Link header. search has the same meaning as on the list endpoint.

Count users matching the filters › query Parameters

search

string

Count users matching the filters › Responses

200

Number of resources matching the filters

Count

count

integer · int64

me organizations