Toucan Public API (v0)

The Toucan API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.

Authentication

bearer

Most of the resources will require you to be authenticated to access them, it is done through a Bearer token, for more information on how to login and get a token, see the dedicated authentication page

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Users

This resource represents a Toucan user on your instance. All these routes require having an ADMIN role to access the users.

Bulk insert/update users

This route requires a minimum user role: ADMIN

Create or update multiple users at once

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

required

Array of objects (BulkUserDTO) [ items ]

An array of users to insert or update

Array

username required	string A string containing the unique identifier of a user, must be an email
roles required	Array of strings Items Enum: "USER" "ADMIN" "SUPER_ADMIN" An array containing the roles of the user
groups	Array of strings An array containing the groups name the user is part of
auth_type required	string Enum: "local_set_by_admin" "local_email_generated" "sso" The authentication type of the user
password	string Deprecated A string containing the password of the user If this field is not set, the user will receive an email to generate a password
	object An object containing the privileges of the user, the keys represent the small apps uid
attributes	object An arbitrary object containing the user attributes
expirationDate	string The date when the user will be automatically deactivated
type required	string Enum: "new" "update" A string to specify whether you want to create or update user

Responses

Request samples

Payload

Content type

application/json

{"users": [{"username": "username@email.com",
"roles": ["USER"
],
"groups": ["my_group"
],
"auth_type": "sso",
"password": "p4ssw0rD",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"attributes": {"foo": "bar"
},
"expirationDate": "2021-01-01",
"type": "new"
}
]
}

Response samples

201
401
403

Content type

application/json

{"summary": {"errors": ["string"
]
}
}

Get a user

This route requires a minimum user role: ADMIN

Retrieve a user information by its username

Authorizations:

bearer

path Parameters

username

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403
404

Content type

application/json

{"username": "username@email.com",
"roles": ["USER"
],
"groups": ["my_group"
],
"activated": true,
"createdBy": "admin@email.com",
"auth_type": "local_set_by_admin",
"deleted": true,
"activatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"lastView": "2019-08-24T14:15:22Z",
"logins": ["string"
],
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"attributes": {"foo": "bar"
},
"expirationDate": "2021-01-01"
}

Delete a user

This route requires a minimum user role: ADMIN

Delete a user by its username

Authorizations:

bearer

path Parameters

username

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

401
403
404

Content type

application/json

{"error": "string"
}

Update a user

This route requires a minimum user role: ADMIN

Update a user by its username

Authorizations:

bearer

path Parameters

username

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

roles	Array of strings Items Enum: "USER" "ADMIN" "SUPER_ADMIN" An array containing the roles of the user
groups	Array of strings An array containing the groups name the user is part of
	object An object containing the privileges of the user, the keys represent the small apps uid
password	string Deprecated A string containing the password of the user
auth_type	string Enum: "local_set_by_admin" "local_email_generated" "sso" The authentication type of the user
attributes	object Default: {} An arbitrary object containing the user attributes
expirationDate	string The date when the user will be automatically deactivated

Responses

Request samples

Payload

Content type

application/json

{"roles": ["USER"
],
"groups": ["my_group"
],
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"password": "string",
"auth_type": "sso",
"attributes": {"foo": "bar"
},
"expirationDate": "2021-01-01"
}

Response samples

200
401
403
404

Content type

application/json

{ }

Get all users

This route requires a minimum user role: ADMIN

Retrieve all the users information

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403

Content type

application/json

{"data": [{ }
],
"meta": {"page": 0,
"limit": 0,
"total": 0,
"lastPage": 0
}
}

Create a user

This route requires a minimum user role: ADMIN

Create a user

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

username required	string A string containing the unique identifier of a user, must be an email
roles required	Array of strings Items Enum: "USER" "ADMIN" "SUPER_ADMIN" An array containing the roles of the user
groups	Array of strings An array containing the groups name the user is part of
auth_type required	string Enum: "local_set_by_admin" "local_email_generated" "sso" The authentication type of the user
password	string Deprecated A string containing the password of the user If this field is not set, the user will receive an email to generate a password
	object An object containing the privileges of the user, the keys represent the small apps uid
attributes	object An arbitrary object containing the user attributes
expirationDate	string The date when the user will be automatically deactivated

Responses

Request samples

Payload

Content type

application/json

{"username": "username@email.com",
"roles": ["USER"
],
"groups": ["my_group"
],
"auth_type": "sso",
"password": "p4ssw0rD",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"attributes": {"foo": "bar"
},
"expirationDate": "2021-01-01"
}

Response samples

201
401
403

Content type

application/json

{ }

Session

This resource represents your current user session (represented by the Bearer token in your Authorization header)

Who am I?

Retrieve the user information you are currently logged in as

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401

Content type

application/json

{"username": "username@email.com",
"roles": ["USER"
],
"groups": ["my_group"
],
"activated": true,
"createdBy": "admin@email.com",
"auth_type": "local_set_by_admin",
"deleted": true,
"activatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"lastView": "2019-08-24T14:15:22Z",
"logins": ["string"
],
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"attributes": {"foo": "bar"
},
"expirationDate": "2021-01-01"
}

System

This resource represents current system informations

Get basic system information

Retrieve the system information such as current version

Responses

Response samples

200

Content type

application/json

{"version": "0.0.1"
}

Small Apps

This resource represents a Toucan small app on your instance. All these routes require having an ADMIN role to access the users.

Create a Small App

This route requires a minimum user role: ADMIN

Create a small app

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

name required	string The name of the small app
position	number The position of the small app in the home page
default_viewer_role required	string Enum: "USER" "ADMIN" "SUPER_ADMIN" The default role required to view the small app This property requires a minimum user role: SUPER_ADMIN
default_contributor_role required	string Enum: "USER" "ADMIN" "SUPER_ADMIN" The default role required to contribute to the small app This property requires a minimum user role: SUPER_ADMIN
automatic_preprocess required	boolean A boolean indicating whether the small app has automatic preprocess enabled
expires_at	string <date-time> The date of expiration of the small app
fromTemplate	string A string representing the template from where the application is created, if applicable
duplicateOf	string The UID of the small app this app as been copied from

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"position": 0,
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"automatic_preprocess": true,
"expires_at": "2019-08-24T14:15:22Z",
"fromTemplate": "string",
"duplicateOf": "string"
}

Response samples

201
401
403
409

Content type

application/json

{"uid": "string",
"name": "string",
"url": "string",
"position": 0,
"automatic_preprocess": true,
"duplicateProcess": true,
"realDataProcess": 0,
"duplicateOf": "string",
"fromTemplate": { },
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"expires_at": "2019-08-24T14:15:22Z",
"staging": {"last_update": "2019-08-24T14:15:22Z"
},
"production": {"last_update": "2019-08-24T14:15:22Z"
}
}

Get all Small Apps

This route requires a minimum user role: USER

Retrieve all the small apps your user has access to

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403

Content type

application/json

{"data": [{"uid": "string",
"name": "string",
"url": "string",
"position": 0,
"automatic_preprocess": true,
"duplicateProcess": true,
"realDataProcess": 0,
"duplicateOf": "string",
"fromTemplate": { },
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"expires_at": "2019-08-24T14:15:22Z",
"staging": {"last_update": "2019-08-24T14:15:22Z"
},
"production": {"last_update": "2019-08-24T14:15:22Z"
}
}
],
"meta": {"page": 0,
"limit": 0,
"total": 0,
"lastPage": 0
}
}

Create a Small App from a master app

This route requires a minimum user role: ADMIN

Create a small app from a master app

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

name required	string The name of the small app
masterApp required	string The smallApp that will be used as a master for this smallApp
variables	object An object containing the variables that will be used to replace the placeholders to generate the Small App config files
force	object Default: false A boolean indicated whether the action should be forced even if the Small App already exists. Setting it to `true` will update the small app with the content of the master app Be careful, old variables will be erased, you need to specify them again

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"masterApp": "string",
"variables": { },
"force": false
}

Response samples

201
401
403
409

Content type

application/json

{"uid": "string",
"name": "string",
"url": "string",
"position": 0,
"automatic_preprocess": true,
"duplicateProcess": true,
"realDataProcess": 0,
"duplicateOf": "string",
"fromTemplate": { },
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"expires_at": "2019-08-24T14:15:22Z",
"staging": {"last_update": "2019-08-24T14:15:22Z"
},
"production": {"last_update": "2019-08-24T14:15:22Z"
}
}

Get a Small App

This route requires a minimum user role: USER

Retrieve a small app your user has access to by its UID

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403

Content type

application/json

{"uid": "string",
"name": "string",
"url": "string",
"position": 0,
"automatic_preprocess": true,
"duplicateProcess": true,
"realDataProcess": 0,
"duplicateOf": "string",
"fromTemplate": { },
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"expires_at": "2019-08-24T14:15:22Z",
"staging": {"last_update": "2019-08-24T14:15:22Z"
},
"production": {"last_update": "2019-08-24T14:15:22Z"
}
}

Delete a Small App

This route requires a minimum user role: ADMIN

Delete a small app by its UID

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

401
403

Content type

application/json

{"error": "string"
}

Update a Small App

This route requires a minimum user role: ADMIN

Update a small app by its UID

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

name required	string The name of the small app
position required	number The position of the small app in the home page
default_viewer_role required	string Enum: "USER" "ADMIN" "SUPER_ADMIN" The default role required to view the small app
default_contributor_role required	string Enum: "USER" "ADMIN" "SUPER_ADMIN" The default role required to contribute to the small app
automatic_preprocess required	boolean A boolean indicating whether the small app has automatic preprocess enabled
expires_at required	string <date-time> The date of expiration of the small app

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"position": 0,
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"automatic_preprocess": true,
"expires_at": "2019-08-24T14:15:22Z"
}

Response samples

200
401
403

Content type

application/json

{"uid": "string",
"name": "string",
"url": "string",
"position": 0,
"automatic_preprocess": true,
"duplicateProcess": true,
"realDataProcess": 0,
"duplicateOf": "string",
"fromTemplate": { },
"default_viewer_role": "USER",
"default_contributor_role": "USER",
"expires_at": "2019-08-24T14:15:22Z",
"staging": {"last_update": "2019-08-24T14:15:22Z"
},
"production": {"last_update": "2019-08-24T14:15:22Z"
}
}

Groups

This resource represents a Toucan group on your instance. All these routes require having an ADMIN role to access the groups.

Create a group

This route requires a minimum user role: ADMIN

Create a group

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

name required	string The unique identifier of the group. Cannot be changed
	object An object containing the privileges of the users part of this group, the keys represent the small apps uid
use_group_privileges required	boolean A boolean representing wether the users of this group should use the group privileges instead of the user one

Responses

Request samples

Payload

Content type

application/json

{"name": "my_group",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}

Response samples

201
401
403

Content type

application/json

{"name": "string",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}

Get all groups

This route requires a minimum user role: USER

Retrieve all the groups your user has access to

Authorizations:

bearer

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403

Content type

application/json

{"data": [{"name": "string",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}
],
"meta": {"page": 0,
"limit": 0,
"total": 0,
"lastPage": 0
}
}

Get a group

This route requires a minimum user role: USER

Retrieve a group your user has access to by its name

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

200
401
403

Content type

application/json

{"name": "string",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}

Delete a group

This route requires a minimum user role: ADMIN

Delete a group by its name

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Responses

Response samples

401
403

Content type

application/json

{"error": "string"
}

Update a group

This route requires a minimum user role: ADMIN

Update a group by its name

Authorizations:

bearer

path Parameters

id

required

string

header Parameters

Authorization

string

Toucan Bearer Token, see Authentication

Request Body schema: application/json

required	object An object containing the privileges of the users part of this group, the keys represent the small apps uid
use_group_privileges	boolean A boolean representing wether the users of this group should use the group privileges instead of the user one

Responses

Request samples

Payload

Content type

application/json

{"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}

Response samples

200
401
403

Content type

application/json

{"name": "string",
"privileges": {"demo": ["view"
],
"new-demo": ["contribute"
],
"my-small-app": ["own"
]
},
"use_group_privileges": true
}