REST API

REST API is not complete yet, please add missing functionality with pull requests to devel branch.

If you are in a hurry, you can use these to have more functionality:

• http://restheart.org
• http://vulcanjs.org

Wekan REST API

The REST API allows you to control and extend Wekan with ease.

If you are an end-user and not a dev or a tester, create an issue to request new APIs.

All API calls in the documentation are made using curl. However, you are free to use Java / Python / PHP / Golang / Ruby / Swift / Objective-C / Rust / Scala / C# or any other programming languages.

Production Security Concerns

When calling a production Wekan server, ensure it is running via HTTPS and has a valid SSL Certificate. The login method requires you to post your username and password in plaintext, which is why we highly suggest only calling the REST login api over HTTPS. Also, few things to note:

• Only call via HTTPS
• Implement a timed authorization token expiration strategy
• Ensure the calling user only has permissions for what they are calling and no more

Summary

Authentication

HTTP Method	Url	Short Description
POST	/users/login	Authenticate with the REST API.

Users

HTTP Method	Url	Short Description
POST	/users/register	Register a new user.
POST	/api/users	Create a new user.
PUT	/api/users/:id	Disable an existing user.
PUT	/api/users/:id	Enable an existing user.
PUT	/api/users/:id	Admin takes the ownership.
DELETE	/api/users/:id	Delete an existing user. (Warning)
GET	/api/users/:id	Gets a user's information.
GET	/api/users	All of the users.
GET	/api/user	Gets a logged-in user.

---

Login

URL	Requires Auth	HTTP Method
/users/login	no	POST

Payload

Authentication with username

Argument	Example	Required	Description
username	myusername	Required	Your username
password	my$up3erP@ssw0rd	Required	Your password

Authentication with email

Argument	Example	Required	Description
email	[email protected]	Required	Your email
password	my$up3erP@ssw0rd	Required	Your password

• Notes:
• You will need to provide the token for any of the authenticated methods.

Example Call - As Form Data

curl http://localhost:3000/users/login \
     -d "username=myusername&password=mypassword"

curl http://localhost:3000/users/login \
     -d "[email protected]&password=mypassword"

Example Call - As JSON

curl -H "Content-type:application/json" \
      http://localhost:3000/users/login \
      -d '{ "username": "myusername", "password": "mypassword" }'

curl -H "Content-type:application/json" \
      http://localhost:3000/users/login \
      -d '{ "email": "[email protected]", "password": "mypassword" }'

Result

{
  "id": "user id",
  "token": "string",
  "tokenExpires": "ISO encoded date string"
}

Result example

{
  "id": "XQMZgynx9M79qTtQc",
  "token": "ExMp2s9ML1JNp_l11sIfINPT3wykZ1SsVwg-cnxKdc8",
  "tokenExpires": "2017-12-15T00:47:26.303Z"
}

User Register

URL	Requires Auth	HTTP Method
/users/register	no	POST

Payload

Argument	Example	Required	Description
username	myusername	Required	Your username
password	my$up3erP@ssw0rd	Required	Your password
email	[email protected]	Required	Your email

• Notes:
• You will need to provide the token for any of the authenticated methods.

Example Call - As Form Data

curl http://localhost:3000/users/register \
     -d "username=myusername&password=mypassword&[email protected]"

Example Call - As JSON

curl -H "Content-type:application/json" \
      http://localhost:3000/users/register \
      -d '{ "username": "myusername", "password": "mypassword", "email": "[email protected]" }'

Result

{
  "id": "user id",
  "token": "string",
  "tokenExpires": "ISO encoded date string"
}

Result example

{
  "id": "XQMZgynx9M79qTtQc",
  "token": "ExMp2s9ML1JNp_l11sIfINPT3wykZ1SsVwg-cnxKdc8",
  "tokenExpires": "2017-12-15T00:47:26.303Z"
}

User Create

URL	Requires Admin Auth	HTTP Method
/api/users	yes	POST

Payload

Argument	Example	Required	Description
username	myusername	Required	Your username
password	my$up3erP@ssw0rd	Required	Your password
email	[email protected]	Required	Your email

• Notes:
• You will need to provide the token for any of the authenticated methods.

Example Call - As Form Data

curl  -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      -X POST \
      http://localhost:3000/api/users \
      -d "username=myusername&password=mypassword&[email protected]"

Example Call - As JSON

curl  -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      -H "Content-type:application/json" \
      -X POST \
      http://localhost:3000/api/users \
      -d '{ "username": "myusername", "password": "mypassword", "email": "[email protected]" }'

Example of all steps of create user

1. Login

curl http://example.com/users/login \
     -d "username=YOUR-USERNAME-HERE&password=YOUR-PASSWORD-HERE"

As response you get your id and token:

"id":"YOUR-ID-HERE","token":"YOUR-TOKEN-HERE","tokenExpires":"2017-12-23T21:07:10.395Z"}

2. Create user. Works both when serf-register enabled and disabled.

curl  -H "Authorization: Bearer YOUR-TOKEN-HERE" \
      -H "Content-type:application/json" \
      -X POST \
      http://example.com/api/users \
      -d '{ "username": "tester", "password": "tester", "email": "[email protected]", "fromAdmin": "true" }'

As reply you get new user's id.

{"id":"NEW-USER-ID-HERE"}

3. You can get user details with your new user's id:

curl -H "Authorization: Bearer YOUR-TOKEN-HERE" \
      http://example.com/api/users/NEW-USER-ID-HERE

Result

Returns the id of the created user.

{
  "_id": "user id"
}

Result example

{
  "_id": "EnhMbvxh65Hr7YvtG"
}

User Delete

IMPORTANT : Should not be used as long as this bug exists.

URL	Requires Admin Auth	HTTP Method
/api/users/:id	yes	DELETE

Parameters

Argument	Example	Required	Description
id	BsNr28znDkG8aeo7W	Required	The id of the user to delete.

Example Call

curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      -X DELETE \
      http://localhost:3000/api/users/EnhMbvxh65Hr7YvtG    

Example Result

Returns the id of the deleted user.

{
  "_id": "EnhMbvxh65Hr7YvtG"
}

User Information

Retrieves information about a user.

URL	Requires Admin Auth	HTTP Method
/api/users/:id	yes	GET

• Notes:
• You will need to provide the token for any of the authenticated methods.
• Only the admin user (the first user) can call the REST API.

Example Call

curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      http://localhost:3000/api/users/XQMZgynx9M79qTtQc

Result example

{
  "_id": "XQMZgynx9M79qTtQc",
  "createdAt": "2017-09-13T06:45:53.127Z",
  "services": {
    "password": {
      "bcrypt": "$2a$10$CRZrpT4x.VpG2FdJxR3rN.9m0NbQb0OPsSPBDAZukggxrskMtWA8."
    },
    "email": {
      "verificationTokens": [
        {
          "token": "8rzwpq_So2PVYHVSfrcc5f5QZnuV2wEtu7QRQGwOJx8",
          "address": "[email protected]",
          "when": "2017-09-13T06:45:53.157Z"
        }
      ]
    },
    "resume": {
      "loginTokens": [
        {
          "when": "2017-09-13T06:45:53.265Z",
          "hashedToken": "CY/PWeDa3fAkl+k94+GWzCtpB5nPcVxLzzzjXs4kI3A="
        },
        {
          "when": "2017-09-16T06:06:19.741Z",
          "hashedToken": "74MQNXfsgjkItx/gpgPb29Y0MSNAvBrsnSGQmr4YGvQ="
        }
      ]
    }
  },
  "username": "john",
  "emails": [
    {
      "address": "[email protected]",
      "verified": false
    }
  ],
  "isAdmin": true,
  "profile": {}
}

Information about boards of user

curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      http://localhost:3000/api/users/XQMZgynx9M79qTtQc/boards

User List

Retrieves the user list.

URL	Requires Admin Auth	HTTP Method
/api/users	yes	GET

• Notes:
• You will need to provide the token for any of the authenticated methods.
• Only the admin user (the first user) can call the REST API.

Example Call

curl -H "Authorization: Bearer cwUZ3ZsTaE6ni2R3ppSkYd-KrDvxsLcBIkSVfOCfIkA" \
      http://localhost:3000/api/users

Result

[
  {
    "_id": "user id",
    "username": "string"
  }
]

Result example

[
  {
    "_id": "XQMZgynx9M79qTtQc",
    "username": "admin"
  },
  {
    "_id": "vy4WYj7k7NBhf3AFc",
    "username": "john"
  }
]

User Logged-in

Retrieves information about a logged-in user with his auth token.

URL	Requires Auth	HTTP Method
/api/user	yes	GET

• Notes:
• You will need to provide the token for any of the authenticated methods.

Example Call

curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
      http://localhost:3000/api/user

Result example

{
  "_id": "vy4WYj7k7NBhf3AFc",
  "createdAt": "2017-09-16T05:51:30.339Z",
  "username": "john",
  "emails": [
    {
      "address": "[email protected]",
      "verified": false
    }
  ],
  "profile": {}
}

Disable a user (the user is not allowed to login and his login tokens are purged)

URL	Requires Admin Auth	HTTP Method
/api/users/:id	yes	PUT

curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
     -H "Content-type:application/json" \
     -X PUT \
     http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
     -d '{ "action": "disableLogin" }'

Enable a user

URL	Requires Admin Auth	HTTP Method
/api/users/:id	yes	PUT

curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
     -H "Content-type:application/json" \
     -X PUT \
     http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
     -d '{ "action": "enableLogin" }'

The admin takes the ownership of ALL boards of the user (archived and not archived) where the user is admin on.

URL	Requires Admin Auth	HTTP Method
/api/users/:id	yes	PUT

curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
     -H "Content-type:application/json" \
     -X PUT \
     http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
     -d '{ "action": "takeOwnership" }'