Users Endpoint

Endpoint Overview

General User Operations

GET: /admin/users : return all users
GET: /admin/users/[iri | email | username]/<identifier> : return single user identified by [IRI | email | username]
POST: /admin/users/ : create new user
PUT: /admin/users/iri/<userIri>/BasicUserInformation : update user's basic user information
PUT: /admin/users/iri/<userIri>/Password : update user's password
PUT: /admin/users/iri/<userIri>/Status : update user's status
DELETE: /admin/users/iri/<userIri> : delete user (set status to false)

Project membership operations

GET: /admin/users/iri/<userIri>/project-memberships : get user's project memberships
POST: /admin/users/iri/<userIri>/project-memberships/<projectIri> : add user to project (to ProjectMember group)
DELETE: /admin/users/iri/<userIri>/project-memberships/<projectIri> : remove user from project (to ProjectMember group)

Group membership operations

GET: /admin/users/iri/<userIri>/project-admin-memberships : get user's ProjectAdmin group memberships
POST: /admin/users/iri/<userIri>/project-admin-memberships/<projectIri> : add user to ProjectAdmin group
DELETE: /admin/users/iri/<userIri>/project-admin-memberships/<projectIri> : remove user from ProjectAdmin group
GET: /admin/users/iri/<userIri>/group-memberships : get user's normal group memberships
POST: /admin/users/iri/<userIri>/group-memberships/<groupIri> : add user to normal group
DELETE: /admin/users/iri/<userIri>/group-memberships/<groupIri> : remove user from normal group
PUT: /admin/users/iri/<userIri>/SystemAdmin : Add/remove user to/from SystemAdmin group

User Operations

Get users

Required permission: SystemAdmin
GET: /admin/users

Get user

Required permission:
- SystemAdmin / self: for getting all properties
- All other users: for getting only the public properties (givenName and familyName)
GET:/admin/users/[iri | email | username ]/<identifier>

Create user

Required permission: none, self-registration is allowed
Required information: email (unique), given name, family name, password, status, systemAdmin
Username restrictions:
- 4 - 50 characters long
- Only contains alphanumeric characters, underscore and dot.
- Underscore and dot can't be at the end or start of a username
- Underscore or dot can't be used multiple times in a row
Returns information about the newly created user
POST: /admin/users
BODY:

    {
  "email": "donald.duck@example.org",
  "givenName": "Donald",
  "familyName": "Duck",
  "username": "donald.duck",
  "password": "test",
  "status": true,
  "lang": "en",
  "systemAdmin": false
}

Additionally, each user can have an optional custom IRI (of Knora IRI form) specified by the id in the request body as below:

    {
  "id": "http://rdfh.ch/users/FnjFfIQFVDvI7ex8zSyUyw",
  "email": "donald.duck@example.org",
  "givenName": "Donald",
  "familyName": "Duck",
  "username": "donald.duck",
  "password": "test",
  "status": true,
  "lang": "en",
  "systemAdmin": false
}

Update basic user information**

Required permission: SystemAdmin / self
Changeable information: username, email, given name, family name, password, status, SystemAdmin membership
TypeScript Docs: userFormats - ChangeUserApiRequestADM
PUT: /admin/users/iri/<userIri>/BasicUserInformation
BODY:

    {
  "username": "donald.big.duck",
  "email": "donald.big.duck@example.org",
  "givenName": "Big Donald",
  "familyName": "Duckmann",
  "lang": "de"
}

Update user's password

Required permission: SystemAdmin / self
Changeable information: password
PUT: /admin/users/iri/<userIri>/Password
BODY:

    {
  "requesterPassword": "test",
  "newPassword": "test1234"
}

Delete user

Required permission: SystemAdmin / self
Remark: The same as updating a user and changing status to false. To un-delete, set status to true.
PUT: /admin/users/iri/<userIri>/Status
BODY:

{
    "status": false // true or false
}

Delete user (-\update user)**

Required permission: SystemAdmin / self
Remark: The same as updating a user and changing status to false. To un-delete, set status to true.
DELETE: /admin/users/iri/<userIri>
BODY: empty

User's project membership operations

Get user's project memberships

GET: /admin/users/iri/<userIri>/project-memberships

Add/remove user to/from project

Required permission: SystemAdmin / ProjectAdmin / self (if project self-assignment is enabled)
Required information: project IRI, user IRI
Effects: knora-base:isInProject user property
POST / DELETE: /admin/users/iri/<userIri>/project-memberships/<projectIri>
BODY: empty

Note: When a user is project admin in the same project, his project admin membership will be removed as well.

User's group membership operations

Get user's project admin memberships

GET: /admin/users/iri/<userIri>/project-admin-memberships

Add/remove user to/from project admin group

Required permission: SystemAdmin / ProjectAdmin
Required information: project IRI, user IRI
Effects: knora-base:isInProjectAdminGroup user property
POST / DELETE: /admin/users/iri/<userIri>/project-admin-memberships/<projectIri>
BODY: empty

Note: In order to add a user to a project admin group, the user needs to be member of that project.

Get user's group memberships**

GET: /admin/users/iri/<userIri>/group-memberships

Add/remove user to/from 'normal' group (not SystemAdmin or ProjectAdmin)

Required permission: SystemAdmin / hasProjectAllAdminPermission / hasProjectAllGroupAdminPermission / hasProjectRestrictedGroupAdminPermission (for this group) / User (if group self-assignment is enabled)
Required information: group IRI, user IRI
Effects: knora-base:isInGroup
POST / DELETE: /admin/users/iri/<userIri>/group-memberships/<groupIri>
BODY: empty

Add/remove user to/from system admin group

Required permission: SystemAdmin / self
Effects property: knora-base:isInSystemAdminGroup with value true or false
PUT: /admin/users/iri/<userIri>/SystemAdmin
BODY:

{
  "systemAdmin": false
}

Example Data

The following is an example for user information stored in the admin named graph:

<http://rdfh.ch/users/c266a56709>
    rdf:type knora-admin:User ;
    knora-admin:username "user01.user1"^^xsd:string ;
    knora-admin:email "user01.user1@example.com"^^xsd:string ;
    knora-admin:givenName "User01"^^xsd:string ;
    knora-admin:familyName "User"^^xsd:string ;
    knora-admin:password "$e0801$FGl9FDIWw+D83OeNPGmD9u2VTqIkJopIQECgmb2DSWQLS0TeKSvYoWAkbEv6KxePPlCI3CP9MmVHuvnWv8/kag==$mlegCYdGXt+ghuo8i0rLjgOiNnGDW604Q5g/v7zwBPU="^^xsd:string ;
    knora-admin:preferredLanguage "de"^^xsd:string ;
    knora-admin:status "true"^^xsd:boolean ;
    knora-admin:isInProject <http://rdfh.ch/projects/00FF> ;
    knora-admin:isInSystemAdminGroup "false"^^xsd:boolean ;
    knora-admin:isInProjectAdminGroup <http://rdfh.ch/projects/00FF> .