API: Users

Actions

Link Description Condition
lock Restrict the user from logging in and performing any actions not locked; Permission: Administrator
show Link to the OpenProject user page (HTML)  
unlock Allow a locked user to login and act again locked; Permission: Administrator
updateImmediately Updates the user’s attributes. Permission: Administrator, manage_user global permission
delete Permanently remove a user from the instance Permission: Administrator, self-delete

Linked Properties

Link Description Type Constraints Supported operations Condition
self This user User not null READ  
auth_source Link to the user’s auth source (endpoint not yet implemented) AuthSource   READ / WRITE Permission: Administrator
members Link to collection of all the user’s memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. MemberCollection   READ Permission: view members or manage members in any project

Depending on custom fields defined for users, additional links might exist.

Local Properties

Property Description Type Constraints Supported operations Condition
id User’s id Integer x > 0 READ  
login User’s login name String unique, 256 max length READ / WRITE Permission: Administrator, manage_user global permission
firstName User’s first name String 30 max length READ / WRITE Permission: Administrator, manage_user global permission
lastName User’s last name String 30 max length READ / WRITE Permission: Administrator, manage_user global permission
name User’s full name, formatting depends on instance settings String   READ  
email User’s email address String unique, 60 max length READ / WRITE E-Mail address not hidden, Permission: Administrator, manage_user global permission
admin Flag indicating whether or not the user is an admin Boolean in: [true, false] READ / WRITE Permission: Administrator
avatar URL to user’s avatar Url   READ  
status The current activation status of the user (see below) String in: [“active”, “registered”, “locked”, “invited”] READ  
language User’s language String ISO 639-1 READ / WRITE Permission: Administrator, manage_user global permission
password User’s password for the default password authentication String   WRITE Permission: Administrator
identity_url User’s identity_url for OmniAuth authentication String   READ / WRITE Permission: Administrator
createdAt Time of creation DateTime   READ  
updatedAt Time of the most recent change to the user DateTime   READ  

Depending on custom fields defined for users, additional properties might exist.

The status of a user can be one of:

  • active - the user can log in with the account right away

  • invited - the user is invited and is pending registration

If the user’s status is set to active during creation a means of authentication has to be provided which is one of the following:

  • password - The password with which the user logs in.

  • auth_source - Link to an LDAP auth source.

  • identity_url - The identity URL of an OmniAuth authentication provider.

If all of these are missing the creation will fail with an “missing password” error.

The language is limited to those activated in the system.

Due to data privacy, the user’s properties are limited to reveal as little about the user as possible. Thus login, firstName, lastName, language, createdAt and updatedAt are hidden for all users except for admins or the user themselves.

Please note that custom fields are not yet supported by the api although the backend supports them.

Methods

List users

Lists users. Only administrators or users with manage_user global permission have permission to do this.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • status: Status the user has

  • group: Name of the group in which to-be-listed users are members.

  • name: Filter users in whose first or last names, or email addresses the given string occurs.

  • login: User’s login

Example:
[{ "status": { "operator": "=", "values": ["invited"] } }, { "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["h.wurst@openproject.com"] } }]

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

Example:
[["status", "asc"]]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/1",
            "method": "DELETE",
            "title": "Delete j.sheppard"
          },
          "lock": {
            "href": "/api/v3/users/1/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard"
          },
          "self": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          },
          "showUser": {
            "href": "/users/1",
            "type": "text/html"
          },
          "update": {
            "href": "/api/v3/users/1",
            "method": "PATCH",
            "title": "Update j.sheppard"
          }
        },
        "_type": "User",
        "admin": true,
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.com",
        "firstName": "John",
        "id": 1,
        "language": "en",
        "lastName": "Sheppard",
        "login": "j.sheppard",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/users"
    }
  },
  "_type": "Collection",
  "count": 1,
  "total": 2
}

UsersModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/users"
      }
    },
    "total": 2,
    "count": 1,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "showUser": {
              "href": "/users/1",
              "type": "text/html"
            },
            "lock": {
              "href": "/api/v3/users/1/lock",
              "title": "Set lock on j.sheppard",
              "method": "POST"
            },
            "update": {
              "href": "/api/v3/users/1",
              "title": "Update j.sheppard",
              "method": "PATCH"
            },
            "delete": {
              "href": "/api/v3/users/1",
              "title": "Delete j.sheppard",
              "method": "DELETE"
            }
          },
          "id": 1,
          "login": "j.sheppard",
          "firstName": "John",
          "lastName": "Sheppard",
          "email": "shep@mail.com",
          "admin": true,
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "language": "en",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

400

Returned if the client sends an unknown sort column.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": "Unknown sort column."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to list users."
}

Create user

Creates a new user. Only administrators and users with manage_user global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

Valid values for status:

1) “active” - In this case a password has to be provided in addition to the other attributes.

2) “invited” - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user.

No parameters

{
  "admin": false,
  "email": "h.wurst@openproject.com",
  "firstName": "Hans",
  "language": "de",
  "lastName": "Wurst",
  "login": "h.wurst",
  "password": "hunter5",
  "status": "active"
}
{
  "admin": {
    "type": "boolean"
  },
  "email": {
    "type": "string"
  },
  "firstName": {
    "type": "string"
  },
  "language": {
    "type": "string"
  },
  "lastName": {
    "type": "string"
  },
  "login": {
    "type": "string"
  },
  "password": {
    "type": "string"
  },
  "status": {
    "type": "string"
  }
}

201

Created

UserModel

{
  "type": "object",
  "example": {
    "_type": "User",
    "_links": {
      "self": {
        "href": "/api/v3/users/1",
        "title": "j.sheppard"
      },
      "show": {
        "href": "/users/1",
        "type": "text/html"
      },
      "lock": {
        "href": "/api/v3/users/1/lock",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/users/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/users/1",
        "method": "DELETE"
      }
    },
    "id": 1,
    "login": "j.sheppard",
    "firstName": "John",
    "lastName": "Sheppard",
    "email": "shep@mail.com",
    "admin": true,
    "avatar": "https://example.org/users/1/avatar",
    "status": "active",
    "language": "en",
    "createdAt": "2014-05-21T08:51:20Z",
    "updatedAt": "2014-05-21T08:51:20Z"
  },
  "properties": {
    "id": {
      "type": "integer",
      "description": "User's id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "login": {
      "type": "string",
      "description": "User's login name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 256
    },
    "firstName": {
      "type": "string",
      "description": "User's first name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "lastName": {
      "type": "string",
      "description": "User's last name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "name": {
      "type": "string",
      "description": "User's full name, formatting depends on instance settings",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "User's email address\n\n# Conditions\n\nE-Mail address not hidden, **Permission**: Administrator, manage_user global permission",
      "maxLength": 60
    },
    "admin": {
      "type": "boolean",
      "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "avatar": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's avatar",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current activation status of the user (see below)",
      "readOnly": true
    },
    "language": {
      "type": "string",
      "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission"
    },
    "password": {
      "type": "string",
      "description": "User's password for the default password authentication\n\n# Conditions\n\n**Permission**: Administrator",
      "writeOnly": true
    },
    "identity_url": {
      "type": "string",
      "description": "User's identity_url for OmniAuth authentication\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "lock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Restrict the user from logging in and performing any actions\n\n# Conditions\n\nnot locked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "show": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the OpenProject user page (HTML)",
              "readOnly": true
            }
          ]
        },
        "unlock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Allow a locked user to login and act again\n\n# Conditions\n\nlocked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the user's attributes.\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Permanently remove a user from the instance\n\n# Conditions\n\n**Permission**: Administrator, self-delete",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This user\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "auth_source": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the user's auth source (endpoint not yet implemented)\n\n**Resource**: AuthSource\n\n# Conditions\n\n**Permission**: Administrator"
            }
          ]
        },
        "members": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions.\n\n**Resource**: MemberCollection\n\n# Conditions\n\n**Permission**: view members or manage members in any project",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create new users."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "email"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The email address is already taken."
}

View user schema

The schema response use two exemplary custom fields that extend the schema response. Depending on your instance and custom field configuration, the response will look somewhat different.

No parameters

200

OK

{
  "_dependencies": [

  ],
  "_links": {
    "self": {
      "href": "/api/v3/users/schema"
    }
  },
  "_type": "Schema",
  "admin": {
    "hasDefault": false,
    "name": "Administrator",
    "options": {
    },
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "avatar": {
    "hasDefault": false,
    "name": "Avatar",
    "options": {
    },
    "required": false,
    "type": "String",
    "writable": false
  },
  "createdAt": {
    "hasDefault": false,
    "name": "Created on",
    "options": {
    },
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "customField1": {
    "hasDefault": false,
    "name": "User String CF",
    "required": false,
    "type": "String",
    "writable": true
  },
  "customField2": {
    "hasDefault": false,
    "location": "_links",
    "name": "User List cf",
    "required": false,
    "type": "CustomOption",
    "writable": true
  },
  "firstName": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "First name",
    "options": {
    },
    "required": true,
    "type": "String",
    "writable": false
  },
  "id": {
    "hasDefault": false,
    "name": "ID",
    "options": {
    },
    "required": true,
    "type": "Integer",
    "writable": false
  },
  "identityUrl": {
    "hasDefault": false,
    "name": "Identity url",
    "options": {
    },
    "required": false,
    "type": "String",
    "writable": true
  },
  "language": {
    "hasDefault": false,
    "name": "Language",
    "options": {
    },
    "required": false,
    "type": "String",
    "writable": true
  },
  "lastName": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "Last name",
    "options": {
    },
    "required": true,
    "type": "String",
    "writable": false
  },
  "login": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "Username",
    "options": {
    },
    "required": true,
    "type": "String",
    "writable": true
  },
  "mail": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "Email",
    "options": {
    },
    "required": true,
    "type": "String",
    "writable": true
  },
  "password": {
    "hasDefault": false,
    "name": "Password",
    "options": {
    },
    "required": false,
    "type": "Password",
    "writable": false
  },
  "status": {
    "hasDefault": false,
    "name": "Status",
    "options": {
    },
    "required": false,
    "type": "String",
    "writable": true
  },
  "updatedAt": {
    "hasDefault": false,
    "name": "Updated on",
    "options": {
    },
    "required": true,
    "type": "DateTime",
    "writable": false
  }
}

View_user_schemaModel

{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_dependencies": [

    ],
    "id": {
      "type": "Integer",
      "name": "ID",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "login": {
      "type": "String",
      "name": "Username",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "minLength": 1,
      "maxLength": 255,
      "options": {
      }
    },
    "admin": {
      "type": "Boolean",
      "name": "Administrator",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "mail": {
      "type": "String",
      "name": "Email",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "minLength": 1,
      "maxLength": 255,
      "options": {
      }
    },
    "firstName": {
      "type": "String",
      "name": "First name",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "minLength": 1,
      "maxLength": 255,
      "options": {
      }
    },
    "lastName": {
      "type": "String",
      "name": "Last name",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "minLength": 1,
      "maxLength": 255,
      "options": {
      }
    },
    "avatar": {
      "type": "String",
      "name": "Avatar",
      "required": false,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "status": {
      "type": "String",
      "name": "Status",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "identityUrl": {
      "type": "String",
      "name": "Identity url",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "language": {
      "type": "String",
      "name": "Language",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "password": {
      "type": "Password",
      "name": "Password",
      "required": false,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "createdAt": {
      "type": "DateTime",
      "name": "Created on",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "updatedAt": {
      "type": "DateTime",
      "name": "Updated on",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "customField1": {
      "type": "String",
      "name": "User String CF",
      "required": false,
      "hasDefault": false,
      "writable": true
    },
    "customField2": {
      "type": "CustomOption",
      "name": "User List cf",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links"
    },
    "_links": {
      "self": {
        "href": "/api/v3/users/schema"
      }
    }
  }
}

View user

id
string

required path

User id. Use me to reference current user, if any.

Example:
1

200

OK

{
  "_links": {
    "delete": {
      "href": "/api/v3/users/1",
      "method": "DELETE"
    },
    "lock": {
      "href": "/api/v3/users/1/lock",
      "method": "POST"
    },
    "self": {
      "href": "/api/v3/users/1",
      "title": "j.sheppard"
    },
    "show": {
      "href": "/users/1",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/users/1",
      "method": "PATCH"
    }
  },
  "_type": "User",
  "admin": true,
  "avatar": "https://example.org/users/1/avatar",
  "createdAt": "2014-05-21T08:51:20Z",
  "email": "shep@mail.com",
  "firstName": "John",
  "id": 1,
  "language": "en",
  "lastName": "Sheppard",
  "login": "j.sheppard",
  "status": "active",
  "updatedAt": "2014-05-21T08:51:20Z"
}

UserModel

{
  "type": "object",
  "example": {
    "_type": "User",
    "_links": {
      "self": {
        "href": "/api/v3/users/1",
        "title": "j.sheppard"
      },
      "show": {
        "href": "/users/1",
        "type": "text/html"
      },
      "lock": {
        "href": "/api/v3/users/1/lock",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/users/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/users/1",
        "method": "DELETE"
      }
    },
    "id": 1,
    "login": "j.sheppard",
    "firstName": "John",
    "lastName": "Sheppard",
    "email": "shep@mail.com",
    "admin": true,
    "avatar": "https://example.org/users/1/avatar",
    "status": "active",
    "language": "en",
    "createdAt": "2014-05-21T08:51:20Z",
    "updatedAt": "2014-05-21T08:51:20Z"
  },
  "properties": {
    "id": {
      "type": "integer",
      "description": "User's id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "login": {
      "type": "string",
      "description": "User's login name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 256
    },
    "firstName": {
      "type": "string",
      "description": "User's first name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "lastName": {
      "type": "string",
      "description": "User's last name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "name": {
      "type": "string",
      "description": "User's full name, formatting depends on instance settings",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "User's email address\n\n# Conditions\n\nE-Mail address not hidden, **Permission**: Administrator, manage_user global permission",
      "maxLength": 60
    },
    "admin": {
      "type": "boolean",
      "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "avatar": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's avatar",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current activation status of the user (see below)",
      "readOnly": true
    },
    "language": {
      "type": "string",
      "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission"
    },
    "password": {
      "type": "string",
      "description": "User's password for the default password authentication\n\n# Conditions\n\n**Permission**: Administrator",
      "writeOnly": true
    },
    "identity_url": {
      "type": "string",
      "description": "User's identity_url for OmniAuth authentication\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "lock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Restrict the user from logging in and performing any actions\n\n# Conditions\n\nnot locked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "show": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the OpenProject user page (HTML)",
              "readOnly": true
            }
          ]
        },
        "unlock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Allow a locked user to login and act again\n\n# Conditions\n\nlocked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the user's attributes.\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Permanently remove a user from the instance\n\n# Conditions\n\n**Permission**: Administrator, self-delete",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This user\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "auth_source": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the user's auth source (endpoint not yet implemented)\n\n**Resource**: AuthSource\n\n# Conditions\n\n**Permission**: Administrator"
            }
          ]
        },
        "members": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions.\n\n**Resource**: MemberCollection\n\n# Conditions\n\n**Permission**: view members or manage members in any project",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

404

Returned if the user does not exist or if the API user does not have permission to view them.

Required permission The user needs to be locked in if the installation is configured to prevent anonymous access

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}

Update user

Updates the user’s writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

id
integer

required path

User id

Example:
1

{
  "admin": true,
  "email": "h.wurst@openproject.com",
  "firstName": "Hans",
  "language": "en",
  "lastName": "Wurst",
  "login": "h.wurst"
}
{
  "admin": {
    "type": "boolean"
  },
  "email": {
    "type": "string"
  },
  "firstName": {
    "type": "string"
  },
  "language": {
    "type": "string"
  },
  "lastName": {
    "type": "string"
  },
  "login": {
    "type": "string"
  }
}

200

OK

UserModel

{
  "type": "object",
  "example": {
    "_type": "User",
    "_links": {
      "self": {
        "href": "/api/v3/users/1",
        "title": "j.sheppard"
      },
      "show": {
        "href": "/users/1",
        "type": "text/html"
      },
      "lock": {
        "href": "/api/v3/users/1/lock",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/users/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/users/1",
        "method": "DELETE"
      }
    },
    "id": 1,
    "login": "j.sheppard",
    "firstName": "John",
    "lastName": "Sheppard",
    "email": "shep@mail.com",
    "admin": true,
    "avatar": "https://example.org/users/1/avatar",
    "status": "active",
    "language": "en",
    "createdAt": "2014-05-21T08:51:20Z",
    "updatedAt": "2014-05-21T08:51:20Z"
  },
  "properties": {
    "id": {
      "type": "integer",
      "description": "User's id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "login": {
      "type": "string",
      "description": "User's login name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 256
    },
    "firstName": {
      "type": "string",
      "description": "User's first name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "lastName": {
      "type": "string",
      "description": "User's last name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "name": {
      "type": "string",
      "description": "User's full name, formatting depends on instance settings",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "User's email address\n\n# Conditions\n\nE-Mail address not hidden, **Permission**: Administrator, manage_user global permission",
      "maxLength": 60
    },
    "admin": {
      "type": "boolean",
      "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "avatar": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's avatar",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current activation status of the user (see below)",
      "readOnly": true
    },
    "language": {
      "type": "string",
      "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission"
    },
    "password": {
      "type": "string",
      "description": "User's password for the default password authentication\n\n# Conditions\n\n**Permission**: Administrator",
      "writeOnly": true
    },
    "identity_url": {
      "type": "string",
      "description": "User's identity_url for OmniAuth authentication\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "lock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Restrict the user from logging in and performing any actions\n\n# Conditions\n\nnot locked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "show": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the OpenProject user page (HTML)",
              "readOnly": true
            }
          ]
        },
        "unlock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Allow a locked user to login and act again\n\n# Conditions\n\nlocked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the user's attributes.\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Permanently remove a user from the instance\n\n# Conditions\n\n**Permission**: Administrator, self-delete",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This user\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "auth_source": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the user's auth source (endpoint not yet implemented)\n\n**Resource**: AuthSource\n\n# Conditions\n\n**Permission**: Administrator"
            }
          ]
        },
        "members": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions.\n\n**Resource**: MemberCollection\n\n# Conditions\n\n**Permission**: view members or manage members in any project",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrators, manage_user global permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to update the account of this user."
}

404

Returned if the user does not exist or if the API user does not have the necessary permissions to update it.

Required permission: Administrators only (exception: users may update their own accounts)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "email"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The email address is already taken."
}

Delete user

Permanently deletes the specified user account.

id
integer

required path

User id

Example:
1

202

Returned if the account was deleted successfully.

Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

403

Returned if the client does not have sufficient permissions or if deletion of users was disabled in the instance wide settings.

Required permission: Administrators only (exception: users might be able to delete their own accounts)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete the account of this user."
}

404

Returned if the user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist."
}

User update form

id
integer

required path

User id

Example:
1

200

OK

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_user global permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the request user can not be found.

Note: A client without sufficient permissions shall not be able to test for the existence of a membership. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Lock user

id
integer

required path

User id

Example:
1

200

OK

{
  "_links": {
    "delete": {
      "href": "/api/v3/users/1",
      "method": "DELETE"
    },
    "lock": {
      "href": "/api/v3/users/1/lock",
      "method": "POST"
    },
    "self": {
      "href": "/api/v3/users/1",
      "title": "j.sheppard"
    },
    "show": {
      "href": "/users/1",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/users/1",
      "method": "PATCH"
    }
  },
  "_type": "User",
  "admin": true,
  "avatar": "https://example.org/users/1/avatar",
  "createdAt": "2014-05-21T08:51:20Z",
  "email": "shep@mail.com",
  "firstName": "John",
  "id": 1,
  "language": "en",
  "lastName": "Sheppard",
  "login": "j.sheppard",
  "status": "active",
  "updatedAt": "2014-05-21T08:51:20Z"
}

UserModel

{
  "type": "object",
  "example": {
    "_type": "User",
    "_links": {
      "self": {
        "href": "/api/v3/users/1",
        "title": "j.sheppard"
      },
      "show": {
        "href": "/users/1",
        "type": "text/html"
      },
      "lock": {
        "href": "/api/v3/users/1/lock",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/users/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/users/1",
        "method": "DELETE"
      }
    },
    "id": 1,
    "login": "j.sheppard",
    "firstName": "John",
    "lastName": "Sheppard",
    "email": "shep@mail.com",
    "admin": true,
    "avatar": "https://example.org/users/1/avatar",
    "status": "active",
    "language": "en",
    "createdAt": "2014-05-21T08:51:20Z",
    "updatedAt": "2014-05-21T08:51:20Z"
  },
  "properties": {
    "id": {
      "type": "integer",
      "description": "User's id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "login": {
      "type": "string",
      "description": "User's login name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 256
    },
    "firstName": {
      "type": "string",
      "description": "User's first name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "lastName": {
      "type": "string",
      "description": "User's last name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "name": {
      "type": "string",
      "description": "User's full name, formatting depends on instance settings",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "User's email address\n\n# Conditions\n\nE-Mail address not hidden, **Permission**: Administrator, manage_user global permission",
      "maxLength": 60
    },
    "admin": {
      "type": "boolean",
      "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "avatar": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's avatar",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current activation status of the user (see below)",
      "readOnly": true
    },
    "language": {
      "type": "string",
      "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission"
    },
    "password": {
      "type": "string",
      "description": "User's password for the default password authentication\n\n# Conditions\n\n**Permission**: Administrator",
      "writeOnly": true
    },
    "identity_url": {
      "type": "string",
      "description": "User's identity_url for OmniAuth authentication\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "lock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Restrict the user from logging in and performing any actions\n\n# Conditions\n\nnot locked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "show": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the OpenProject user page (HTML)",
              "readOnly": true
            }
          ]
        },
        "unlock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Allow a locked user to login and act again\n\n# Conditions\n\nlocked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the user's attributes.\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Permanently remove a user from the instance\n\n# Conditions\n\n**Permission**: Administrator, self-delete",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This user\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "auth_source": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the user's auth source (endpoint not yet implemented)\n\n**Resource**: AuthSource\n\n# Conditions\n\n**Permission**: Administrator"
            }
          ]
        },
        "members": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions.\n\n**Resource**: MemberCollection\n\n# Conditions\n\n**Permission**: view members or manage members in any project",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Returned if the client tries to lock a user account whose current status does not allow this transition.

Required permission: Administrators only

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
  "message": "The current user account status does not allow this operation."
}

403

Returned if the client does not have sufficient permissions for locking a user.

Required permission: Administrators only

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to lock the account of this user."
}

404

Returned if the user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist."
}

Unlock user

id
integer

required path

User id

Example:
1

200

OK

{
  "_links": {
    "delete": {
      "href": "/api/v3/users/1",
      "method": "DELETE"
    },
    "lock": {
      "href": "/api/v3/users/1/lock",
      "method": "POST"
    },
    "self": {
      "href": "/api/v3/users/1",
      "title": "j.sheppard"
    },
    "show": {
      "href": "/users/1",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/users/1",
      "method": "PATCH"
    }
  },
  "_type": "User",
  "admin": true,
  "avatar": "https://example.org/users/1/avatar",
  "createdAt": "2014-05-21T08:51:20Z",
  "email": "shep@mail.com",
  "firstName": "John",
  "id": 1,
  "language": "en",
  "lastName": "Sheppard",
  "login": "j.sheppard",
  "status": "active",
  "updatedAt": "2014-05-21T08:51:20Z"
}

UserModel

{
  "type": "object",
  "example": {
    "_type": "User",
    "_links": {
      "self": {
        "href": "/api/v3/users/1",
        "title": "j.sheppard"
      },
      "show": {
        "href": "/users/1",
        "type": "text/html"
      },
      "lock": {
        "href": "/api/v3/users/1/lock",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/users/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/users/1",
        "method": "DELETE"
      }
    },
    "id": 1,
    "login": "j.sheppard",
    "firstName": "John",
    "lastName": "Sheppard",
    "email": "shep@mail.com",
    "admin": true,
    "avatar": "https://example.org/users/1/avatar",
    "status": "active",
    "language": "en",
    "createdAt": "2014-05-21T08:51:20Z",
    "updatedAt": "2014-05-21T08:51:20Z"
  },
  "properties": {
    "id": {
      "type": "integer",
      "description": "User's id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "login": {
      "type": "string",
      "description": "User's login name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 256
    },
    "firstName": {
      "type": "string",
      "description": "User's first name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "lastName": {
      "type": "string",
      "description": "User's last name\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
      "maxLength": 30
    },
    "name": {
      "type": "string",
      "description": "User's full name, formatting depends on instance settings",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "User's email address\n\n# Conditions\n\nE-Mail address not hidden, **Permission**: Administrator, manage_user global permission",
      "maxLength": 60
    },
    "admin": {
      "type": "boolean",
      "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "avatar": {
      "type": "string",
      "format": "uri",
      "description": "URL to user's avatar",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current activation status of the user (see below)",
      "readOnly": true
    },
    "language": {
      "type": "string",
      "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission"
    },
    "password": {
      "type": "string",
      "description": "User's password for the default password authentication\n\n# Conditions\n\n**Permission**: Administrator",
      "writeOnly": true
    },
    "identity_url": {
      "type": "string",
      "description": "User's identity_url for OmniAuth authentication\n\n# Conditions\n\n**Permission**: Administrator"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "lock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Restrict the user from logging in and performing any actions\n\n# Conditions\n\nnot locked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "show": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the OpenProject user page (HTML)",
              "readOnly": true
            }
          ]
        },
        "unlock": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Allow a locked user to login and act again\n\n# Conditions\n\nlocked; **Permission**: Administrator",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the user's attributes.\n\n# Conditions\n\n**Permission**: Administrator, manage_user global permission",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Permanently remove a user from the instance\n\n# Conditions\n\n**Permission**: Administrator, self-delete",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This user\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "auth_source": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to the user's auth source (endpoint not yet implemented)\n\n**Resource**: AuthSource\n\n# Conditions\n\n**Permission**: Administrator"
            }
          ]
        },
        "members": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions.\n\n**Resource**: MemberCollection\n\n# Conditions\n\n**Permission**: view members or manage members in any project",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Returned if the client tries to unlock a user account whose current status does not allow this transition.

Required permission: Administrators only

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
  "message": "The current user account status does not allow this operation."
}

403

Returned if the client does not have sufficient permissions for unlocking a user.

Required permission: Administrators only

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to unlock the account of this user."
}

404

Returned if the user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist."
}