API docs by Redocly

Users Keycloak API (v1)

Users Keycloak API

users

createUser

Create a new user

query Parameters
keycloakOnly
boolean
Default: false

Create auth user only during user creation

Request Body schema: application/json
required
username
string

A unique name belonging to a user. Typically used for login

id
string <uuid>

A globally unique (UUID) identifier for the user

externalSystemId
string

A unique ID that corresponds to an external authority

barcode
string

The unique library barcode for this user

active
boolean

A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block

type
string

The class of user like staff or patron; this is different from patronGroup

patronGroup
string <uuid>

A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group

departments
Array of strings <uuid> unique [ items <uuid > ]

A list of UUIDs corresponding to the departments the user belongs to, see /departments API

meta
object

Deprecated

proxyFor
Array of strings

Deprecated

object (Personal Schema)

Personal information about the user

lastName
required
string

The user's surname

firstName
string

The user's given name

middleName
string

The user's middle name (if any)

preferredFirstName
string

The user's preferred name

email
string

The user's email address

pronouns
string <= 300 characters

The user's pronouns

phone
string

The user's primary phone number

mobilePhone
string

The user's mobile phone number

dateOfBirth
string <date-time>

The user's birth date

Array of objects (Address Schema) >= 0 items

Physical addresses associated with the user

preferredContactTypeId
string

Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API

profilePictureLink
string <uri>

Link to the profile picture

enrollmentDate
string <date-time>

The date in which the user joined the organization

expirationDate
string <date-time>

The date for when the user becomes inactive

createdDate
string <date-time>

Deprecated

updatedDate
string <date-time>

Deprecated

object (Metadata Schema)

Metadata about creation and changes to records, provided by the server (client should not provide)

createdDate
required
string <date-time>

Date and time when the record was created

createdByUserId
string <uuid>

ID of the user who created the record (when available)

createdByUsername
string

Username of the user who created the record (when available)

updatedDate
string <date-time>

Date and time when the record was last updated

updatedByUserId
string <uuid>

ID of the user who last updated the record (when available)

updatedByUsername
string

Username of the user who last updated the record (when available)

object (tags)

List of simple tags that can be added to an object

tagList
Array of strings

List of tags

object

Object that contains custom field

property name*
additional property
any
preferredEmailCommunication
Array of strings <= 3 items unique
Items Enum: "Support" "Programs" "Services"

Preferred email communication types

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalSystemId": "string",
  • "barcode": "string",
  • "active": true,
  • "type": "string",
  • "patronGroup": "eb001005-6661-42d5-8ba7-00bd0866bea0",
  • "departments": [
    ],
  • "meta": { },
  • "proxyFor": [
    ],
  • "personal": {
    },
  • "enrollmentDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "tags": {
    },
  • "customFields": { },
  • "preferredEmailCommunication": [
    ]
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalSystemId": "string",
  • "barcode": "string",
  • "active": true,
  • "type": "string",
  • "patronGroup": "eb001005-6661-42d5-8ba7-00bd0866bea0",
  • "departments": [
    ],
  • "meta": { },
  • "proxyFor": [
    ],
  • "personal": {
    },
  • "enrollmentDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "tags": {
    },
  • "customFields": { },
  • "preferredEmailCommunication": [
    ]
}

getUsers

Retrieve a list of users

query Parameters
query
string

A CQL query string with search conditions.

offset
integer >= 0
Default: 0

Skip over a number of elements by specifying an offset value for the query.

limit
integer [ 0 .. 500 ]
Default: 10

Limit the number of elements returned in the response.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "totalRecords": 0,
  • "resultInfo": {
    }
}

deleteUsers

Delete a collection of users selected by a CQL query; | this doesn't delete proxyFor records that reference them

query Parameters
query
string

A CQL query string with search conditions.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

updateUser

Update user with given id

path Parameters
id
required
string <uuid>

Entity id

Request Body schema: application/json
required
username
string

A unique name belonging to a user. Typically used for login

id
string <uuid>

A globally unique (UUID) identifier for the user

externalSystemId
string

A unique ID that corresponds to an external authority

barcode
string

The unique library barcode for this user

active
boolean

A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block

type
string

The class of user like staff or patron; this is different from patronGroup

patronGroup
string <uuid>

A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group

departments
Array of strings <uuid> unique [ items <uuid > ]

A list of UUIDs corresponding to the departments the user belongs to, see /departments API

meta
object

Deprecated

proxyFor
Array of strings

Deprecated

object (Personal Schema)

Personal information about the user

lastName
required
string

The user's surname

firstName
string

The user's given name

middleName
string

The user's middle name (if any)

preferredFirstName
string

The user's preferred name

email
string

The user's email address

pronouns
string <= 300 characters

The user's pronouns

phone
string

The user's primary phone number

mobilePhone
string

The user's mobile phone number

dateOfBirth
string <date-time>

The user's birth date

Array of objects (Address Schema) >= 0 items

Physical addresses associated with the user

preferredContactTypeId
string

Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API

profilePictureLink
string <uri>

Link to the profile picture

enrollmentDate
string <date-time>

The date in which the user joined the organization

expirationDate
string <date-time>

The date for when the user becomes inactive

createdDate
string <date-time>

Deprecated

updatedDate
string <date-time>

Deprecated

object (Metadata Schema)

Metadata about creation and changes to records, provided by the server (client should not provide)

createdDate
required
string <date-time>

Date and time when the record was created

createdByUserId
string <uuid>

ID of the user who created the record (when available)

createdByUsername
string

Username of the user who created the record (when available)

updatedDate
string <date-time>

Date and time when the record was last updated

updatedByUserId
string <uuid>

ID of the user who last updated the record (when available)

updatedByUsername
string

Username of the user who last updated the record (when available)

object (tags)

List of simple tags that can be added to an object

tagList
Array of strings

List of tags

object

Object that contains custom field

property name*
additional property
any
preferredEmailCommunication
Array of strings <= 3 items unique
Items Enum: "Support" "Programs" "Services"

Preferred email communication types

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalSystemId": "string",
  • "barcode": "string",
  • "active": true,
  • "type": "string",
  • "patronGroup": "eb001005-6661-42d5-8ba7-00bd0866bea0",
  • "departments": [
    ],
  • "meta": { },
  • "proxyFor": [
    ],
  • "personal": {
    },
  • "enrollmentDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "tags": {
    },
  • "customFields": { },
  • "preferredEmailCommunication": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

getUser

Get a single user

path Parameters
id
required
string <uuid>

Entity id

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalSystemId": "string",
  • "barcode": "string",
  • "active": true,
  • "type": "string",
  • "patronGroup": "eb001005-6661-42d5-8ba7-00bd0866bea0",
  • "departments": [
    ],
  • "meta": { },
  • "proxyFor": [
    ],
  • "personal": {
    },
  • "enrollmentDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "tags": {
    },
  • "customFields": { },
  • "preferredEmailCommunication": [
    ]
}

deleteUser

Delete user with given id

path Parameters
id
required
string <uuid>

Entity id

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

findPermissions

Finds user permissions by filter. desiredPermissions query parameter is required. Wildcard (*) is supported.

path Parameters
id
required
string <uuid>

Entity id

query Parameters
desiredPermissions
required
Array of strings
Example: desiredPermissions=users.collection.get&desiredPermissions=users.item.*

Permissions of permission prefix to filter by

Responses

Response samples

Content type
application/json
{
  • "permissions": [
    ]
}

getUserBySelfReference

Get a user by self reference

query Parameters
include
Array of strings (Included field)
Items Enum: "groups" "perms" "proxiesfor" "servicepoints" "expanded_perms" "expanded_servicepoints"

Indicates which referenced fields should be populated (de-referenced) by the service

expandPermissions
boolean
Default: false

Whether or not to expand permissions listings

overrideUser
boolean
Default: false

When set to true the real user will be retrieved for ECS login into member tenants

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "patronGroup": {
    },
  • "permissions": {
    },
  • "proxiesFor": [
    ],
  • "servicePointsUser": {
    },
  • "originalTenantId": "string"
}

migration

getMigrations

Retrieve a list of user migrations

query Parameters
query
string

A CQL query string with search conditions.

offset
integer >= 0
Default: 0

Skip over a number of elements by specifying an offset value for the query.

limit
integer [ 0 .. 500 ]
Default: 10

Limit the number of elements returned in the response.

Responses

Response samples

Content type
application/json
{
  • "migrations": [
    ],
  • "totalRecords": 0
}

migrateUsers

Migrate users from mod-users to Keycloak

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "in_progress",
  • "totalRecords": 0,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z"
}

getMigration

Retrieve a user migration

path Parameters
id
required
string <uuid>

Entity id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "in_progress",
  • "totalRecords": 0,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z"
}

deleteMigration

Delete a user migration

path Parameters
id
required
string <uuid>

Entity id

Responses

idp-migration

linkUserIdpMigration

Link users to an identity provider migration operation

Request Body schema: application/json
required
centralTenantId
required
string

Central tenant id that will be used for linking the shadow users

userIds
required
Array of strings <uuid> unique [ items <uuid > ]

A list of user UUIDs that are to be scheduled for IDP linking in central tenant

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "centralTenantId": "string",
  • "userIds": [
    ]
}

unlinkUserIdpMigration

Unlink users from an identity provider migration operation

Request Body schema: application/json
required
centralTenantId
required
string

Central tenant id that will be used for linking the shadow users

userIds
required
Array of strings <uuid> unique [ items <uuid > ]

A list of user UUIDs that are to be scheduled for IDP linking in central tenant

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "centralTenantId": "string",
  • "userIds": [
    ]
}

forgotten-username-password

resetForgottenPassword

called when a user has forgotten a password

Request Body schema: application/json
required
id
string

Id

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

recoverForgottenUsername

called when a user has forgotten a username

Request Body schema: application/json
required
id
string

Id

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

password-reset

passwordReset

Request Body schema: application/json
newPassword
required
string

New password

Responses

Request samples

Content type
application/json
{
  • "newPassword": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

auth-user

checkIfExistsAuthUserById

Check if AuthUser exists for the specified user ID

path Parameters
userId
required
string <uuid>

User ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}

createAuthUser

Check if AuthUser exists for the specified user ID

path Parameters
userId
required
string <uuid>

User ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 0
}