Get a list of users.
This function takes pagination parameters page
and per_page
to restrict the list of users.
GET /users
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
},
{
"id": 2,
"username": "jack_smith",
"name": "Jack Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
}
]
GET /users
[
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"extern_uid": "john.smith",
"provider": "provider_name",
"theme_id": 1,
"color_scheme_id": 2,
"is_admin": false,
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"can_create_group": true,
"current_sign_in_at": "2014-03-19T13:12:15Z",
"two_factor_enabled": true
},
{
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
"state": "blocked",
"created_at": "2012-05-23T08:01:01Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"extern_uid": "jack.smith",
"provider": "provider_name",
"theme_id": 1,
"color_scheme_id": 3,
"is_admin": false,
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"can_create_group": true,
"can_create_project": true,
"projects_limit": 100,
"current_sign_in_at": "2014-03-19T17:54:13Z",
"two_factor_enabled": false
}
]
You can search for users by email or username with: /users?search=John
In addition, you can lookup users by username:
GET /users?username=:username
For example:
GET /users?username=jack_smith
Get a single user.
GET /users/:id
Parameters:
id
(required) - The ID of a user
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"created_at": "2012-05-23T08:00:58Z",
"is_admin": false,
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": ""
}
GET /users/:id
Parameters:
id
(required) - The ID of a user
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"extern_uid": "john.smith",
"provider": "provider_name",
"theme_id": 1,
"color_scheme_id": 2,
"is_admin": false,
"can_create_group": true,
"can_create_project": true,
"projects_limit": 100
}
Creates a new user. Note only administrators can create new users.
POST /users
Parameters:
email
(required) - Emailpassword
(required) - Passwordusername
(required) - Usernamename
(required) - Nameskype
(optional) - Skype IDlinkedin
(optional) - LinkedIntwitter
(optional) - Twitter accountwebsite_url
(optional) - Website URLprojects_limit
(optional) - Number of projects user can createextern_uid
(optional) - External UIDprovider
(optional) - External provider namebio
(optional) - User's biographyadmin
(optional) - User is admin - true or false (default)can_create_group
(optional) - User can create groups - true or falseconfirm
(optional) - Require confirmation - true (default) or false
Modifies an existing user. Only administrators can change attributes of a user.
PUT /users/:id
Parameters:
email
- Emailusername
- Usernamename
- Namepassword
- Passwordskype
- Skype IDlinkedin
- LinkedIntwitter
- Twitter accountwebsite_url
- Website URLprojects_limit
- Limit projects each user can createextern_uid
- External UIDprovider
- External provider namebio
- User's biographyadmin
(optional) - User is admin - true or false (default)can_create_group
(optional) - User can create groups - true or false
Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
still returns a status code 200 OK
.
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
DELETE /users/:id
Parameters:
id
(required) - The ID of the user
Gets currently authenticated user.
GET /user
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"private_token": "dd34asd13as",
"state": "active",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"theme_id": 1,
"color_scheme_id": 2,
"is_admin": false,
"can_create_group": true,
"can_create_project": true,
"projects_limit": 100
}
Get a list of currently authenticated user's SSH keys.
GET /user/keys
[
{
"id": 1,
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
},
{
"id": 3,
"title": "Another Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
}
]
Parameters:
- none
Get a list of a specified user's SSH keys. Available only for admin
GET /users/:uid/keys
Parameters:
uid
(required) - id of specified user
Get a single key.
GET /user/keys/:id
Parameters:
id
(required) - The ID of an SSH key
{
"id": 1,
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
}
Creates a new key owned by the currently authenticated user.
POST /user/keys
Parameters:
title
(required) - new SSH Key's titlekey
(required) - new SSH key
{
"created_at": "2015-01-21T17:44:33.512Z",
"key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
"title": "ABC",
"id": 4
}
Will return created key with status 201 Created
on success. If an
error occurs a 400 Bad Request
is returned with a message explaining the error:
{
"message": {
"fingerprint": [
"has already been taken"
],
"key": [
"has already been taken"
]
}
}
Create new key owned by specified user. Available only for admin
POST /users/:id/keys
Parameters:
id
(required) - id of specified usertitle
(required) - new SSH Key's titlekey
(required) - new SSH key
Will return created key with status 201 Created
on success, or 404 Not found
on fail.
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
or not available results in 200 OK
.
DELETE /user/keys/:id
Parameters:
id
(required) - SSH key ID
Deletes key owned by a specified user. Available only for admin.
DELETE /users/:uid/keys/:id
Parameters:
uid
(required) - id of specified userid
(required) - SSH key ID
Will return 200 OK
on success, or 404 Not found
if either user or key cannot be found.
Get a list of currently authenticated user's emails.
GET /user/emails
[
{
"id": 1,
"email": "email@example.com"
},
{
"id": 3,
"email": "email2@example.com"
}
]
Parameters:
- none
Get a list of a specified user's emails. Available only for admin
GET /users/:uid/emails
Parameters:
uid
(required) - id of specified user
Get a single email.
GET /user/emails/:id
Parameters:
id
(required) - email ID
{
"id": 1,
"email": "email@example.com"
}
Creates a new email owned by the currently authenticated user.
POST /user/emails
Parameters:
email
(required) - email address
{
"id": 4,
"email": "email@example.com"
}
Will return created email with status 201 Created
on success. If an
error occurs a 400 Bad Request
is returned with a message explaining the error:
{
"message": {
"email": [
"has already been taken"
]
}
}
Create new email owned by specified user. Available only for admin
POST /users/:id/emails
Parameters:
id
(required) - id of specified useremail
(required) - email address
Will return created email with status 201 Created
on success, or 404 Not found
on fail.
Deletes email owned by currently authenticated user.
This is an idempotent function and calling it on a email that is already deleted
or not available results in 200 OK
.
DELETE /user/emails/:id
Parameters:
id
(required) - email ID
Deletes email owned by a specified user. Available only for admin.
DELETE /users/:uid/emails/:id
Parameters:
uid
(required) - id of specified userid
(required) - email ID
Will return 200 OK
on success, or 404 Not found
if either user or email cannot be found.
Blocks the specified user. Available only for admin.
PUT /users/:uid/block
Parameters:
uid
(required) - id of specified user
Will return 200 OK
on success, 404 User Not Found
is user cannot be found or
403 Forbidden
when trying to block an already blocked user by LDAP synchronization.
Unblocks the specified user. Available only for admin.
PUT /users/:uid/unblock
Parameters:
uid
(required) - id of specified user
Will return 200 OK
on success, 404 User Not Found
is user cannot be found or
403 Forbidden
when trying to unblock a user blocked by LDAP synchronization.