Reference
Web API
Users

Users

The Users API has methods for managing users.

Create user

Create a user account.

POST /api/users

Body parameters

uid string required: A unique user identifier (cannot contain whitespace and must contain at least one non-digit).

username string: Username. Must be unique if/when specified.

email string: Email address. Must be unique if/when specified.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.ProfileUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base-64 encoded image or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

Response codes

201 Created

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

400 Bad Request

Code sample

curl https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
-H "Content-Type: application/json"
-d "{ 'uid': 'user-1', 'name': 'John Doe', 'directory': 'acme' }"

List users

List users.

GET /api/users

Query parameters

directory_id integer: List users in the specified directory, null lists users from all directories.

suspended boolean: Indicates whether to list suspended users or not.

q string: A query used to find matching items.

tag string: List items with the specified tag.

trashed boolean: Indicates whether trashed items should be listed (default is false). Specify null to return both trashed and non-trashed items.

order_by string: Specifies the sort order and direction for the listing, e.g. "name" or "name+desc"

top integer: Maximum number of items to return in the listing. Should be a value between 0 and 100. Default is 25.

skip integer: The number of items to skip. Used together with top to return a specific range of items (for pagination).

count boolean: false to skip counting the total number of matching items; default is true.

count_only boolean: true to only return the number of matching items; when this is specified the response will only contain the count property.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Code sample

curl https://{WEAVY-SERVER}/api/users?top=20
-H "Authorization: Bearer {API-KEY}"

Get user

Get a user by id.

GET /api/users/{id}

Path parameters

id integer required: Id of user.

Query parameters

trashed boolean: true to return user even if trashed.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Code sample

curl https://{WEAVY-SERVER}/api/users/1
-H "Authorization: Bearer {API-KEY}"

Update user

Update a user.

PATCH /api/users/{id}

Path parameters

id integer required

Body parameters

uid string: A string that uniquely identifies the user (cannot contain whitespace and must contain at least one non-digit).

username string: Username. Must be unique if/when specified.

email string: Email address. Must be unique if/when specified.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.ProfileUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base-64 encoded image or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

Response codes

204 No Content

404 Not Found

400 Bad Request

Code sample

$ curl -X PATCH {WEAVY_SERVER}/api/users/1
-H "Authorization: Bearer {API-KEY}"
-H "Content-Type: application/json"
-d "{ 'name': 'Updated name' }"

Get user (uid)

Get a user by uid.

GET /api/users/{uid}

Path parameters

uid string required: Unique user identifier.

Query parameters

trashed boolean: true to return user even if trashed.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Code sample

curl https://{WEAVY-SERVER}/api/users/user-1
-H "Authorization: Bearer {API-KEY}"

Sync user

Create or update user with specified uid.

PUT /api/users/{uid}

Path parameters

uid string required: Unique user identifier.

Body parameters

username string: Username. Must be unique if/when specified.

email string: Email address. Must be unique if/when specified.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.ProfileUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base-64 encoded image or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

201 Created

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Code sample

$ curl -X PUT {WEAVY_SERVER}/api/users/user-1
-H "Authorization: Bearer {API-KEY}"
-H "Content-Type: application/json"
-d "{ 'name': 'John Doe', 'email': 'john@acme.com' }"

Get authenticated user

Get the authenticated user.

GET /api/user

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Code sample

curl https://{WEAVY-SERVER}/api/user
-H "Authorization: Bearer {ACCESS-TOKEN}"

Trash user

Move a user to the trash.

POST /api/users/{id}/trash

Path parameters

id integer required: Id of the user to trash.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

400 Bad Request

Code sample

$ curl -X POST {WEAVY_SERVER}/api/users/1/trash
-H "Authorization: Bearer {API-KEY}"

Restore user

Restore a user from the trash.

POST /api/users/{id}/restore

Path parameters

id integer required: Id of the user to restore.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "username": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory_id": "integer",
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_admin": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Code sample

$ curl -X POST {WEAVY_SERVER}/api/users/1/restore
-H "Authorization: Bearer {API-KEY}"

List user (autocomplete)

List users based on autocomplete search.

GET /api/users/autocomplete

Query parameters

q string: The search phrase to use.

top integer: Max number of items to returnm defaults to 5.

id integer: Optional app id. When set, the result contains a property indicating wheter the listed users are member of the specified app or not.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Code sample

curl https://{WEAVY-SERVER}/api/users/autocomplete?q=john
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Get access token

Issues an access token for a user. If a user with the with the specified uid does not exists, this endpoint first creates the user and then issues an access_token.

POST /api/users/{uid}/tokens

Path parameters

uid string required: Unique user identifier.

Body parameters

expires_in integer: The lifetime of the access token in seconds, defaults to 3600 seconds (1 hour) when not specified.

Response codes

200 Success

{
  "access_token": "string",
  "expires_in": "integer"
}

Code sample

curl https://{WEAVY-SERVER}/api/users/user-1/tokens
-H "Authorization: Bearer {API-KEY}"
-H "Content-Type: application/json"
-d "{ 'expires_in': 7200 }"

Revoke access token

Revoke all access tokens for the specified user.

DELETE /api/users/{uid}/tokens

Path parameters

uid string required: Unique user identifier.

Response codes

200 Success

Code sample

$ curl -X DELETE {WEAVY_SERVER}/api/users/user-1/tokens
-H "Authorization: Bearer {API-KEY}"

Users

Create user

Body parameters

Response codes

Code sample

List users

Query parameters

Response codes

Code sample

Get user

Path parameters

Query parameters

Response codes

Code sample

Update user

Path parameters

Body parameters

Response codes

Code sample

Get user (uid)

Path parameters

Query parameters

Response codes

Code sample

Sync user

Path parameters

Body parameters

Response codes

Code sample

Get authenticated user

Response codes

Code sample

Trash user

Path parameters

Response codes

Code sample

Restore user

Path parameters

Response codes

Code sample

List user (autocomplete)

Query parameters

Response codes

Code sample

Get access token

Path parameters

Body parameters

Response codes

Code sample

Revoke access token

Path parameters

Response codes

Code sample

Weavy Docs