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> .