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

email string

Email address.

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.UserUp.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 base64 encoded data URI 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",
  "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_suspended": "boolean",
  "is_trashed": "boolean"
}

400 Bad Request

Code sample
curl https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
--json "{ 'uid': 'bugs-bunny', 'name': 'Bugs Bunny', '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 {ACCESS-TOKEN | API-KEY}"

Get user

Get user with specified identifier.

GET /api/users/{user}
Path parameters
user string required

User identifier (id or uid).

Query parameters
trashed boolean

true to return user even if trashed.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl https://{WEAVY-SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"

Update user

Update a user.

PATCH /api/users/{user}
Path parameters
user string required

User identifier (id or uid).

Body parameters
uid string

Unique user identifier (cannot contain whitespace and must contain at least one non-digit).

email string

Email address.

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.UserUp.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 base64 encoded data URI 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",
  "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl -X PATCH https://{WEAVY_SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny' }"

Get authenticated user

Get the authenticated user.

GET /api/user
Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl https://{WEAVY-SERVER}/api/user
-H "Authorization: Bearer {ACCESS-TOKEN}"

Upsert user

Update and return user with specified uid. If the user does not exists it is created.

PUT /api/users/{uid}
Path parameters
uid string required

Unique user identifier.

Body parameters
uid string
email string

Email address.

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.UserUp.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 base64 encoded data URI 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",
  "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_suspended": "boolean",
  "is_trashed": "boolean"
}

201 Created

{
  "id": "integer",
  "uid": "string",
  "display_name": "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl -X PUT https://{WEAVY_SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny', 'email': 'bugs@acme.corp"

Trash user

Move a user to the trash.

POST /api/users/{user}/trash
Path parameters
user string required

User identifier (id or uid) of the user to trash.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl -X POST https://{WEAVY_SERVER}/api/users/bugs-bunny/trash
-H "Authorization: Bearer {API-KEY}"

Restore user

Restore a user from the trash.

POST /api/users/{user}/restore
Path parameters
user string required

User identifier (id or uid) of the user to restore.

Response codes

200 Success

{
  "id": "integer",
  "uid": "string",
  "display_name": "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_suspended": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl -X POST https://{WEAVY_SERVER}/api/users/bugs-bunny/restore
-H "Authorization: Bearer {API-KEY}"

Issue access token

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/{user}/tokens
Path parameters
user string required

User identifier (id or uid).

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/bugs-bunny/tokens
-H "Authorization: Bearer {API-KEY}"
--json "{ 'expires_in': 7200 }"

Revoke access token

Revoke all access tokens for the specified user.

DELETE /api/users/{user}/tokens
Path parameters
user string required

User identifier (id or uid).

Response codes

200 Success

Code sample
curl -X DELETE https://{WEAVY_SERVER}/api/users/bugs-bunny/tokens
-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.

skip integer

Gets or sets the number of items to skip before returning, defaults to 0.

top integer

Max number of items to return, defaults to 5.

count boolean

Count the total number of search results, defaults to false.

id integer

Optional app id. When set, the result contains a property indicating whether 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}"
Weavy Docs