users.md 5.55 KB
Newer Older
Nihad Abbasov's avatar
Nihad Abbasov committed
1 2 3
## List users

Get a list of users.
4
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
Nihad Abbasov's avatar
Nihad Abbasov committed
5 6 7 8 9 10 11 12 13

```
GET /users
```

```json
[
  {
    "id": 1,
14
    "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
15 16
    "email": "john@example.com",
    "name": "John Smith",
17
    "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
18 19 20 21 22
    "created_at": "2012-05-23T08:00:58Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
23 24
    "extern_uid": "john.smith",
    "provider": "provider_name",
Nihad Abbasov's avatar
Nihad Abbasov committed
25
    "theme_id": 1
26
    "color_scheme_id": 2
Nihad Abbasov's avatar
Nihad Abbasov committed
27 28 29
  },
  {
    "id": 2,
30
    "username": "jack_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
31 32
    "email": "jack@example.com",
    "name": "Jack Smith",
33
    "state": "blocked",
Nihad Abbasov's avatar
Nihad Abbasov committed
34 35 36 37 38
    "created_at": "2012-05-23T08:01:01Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
39 40
    "extern_uid": "jack.smith",
    "provider": "provider_name",
Nihad Abbasov's avatar
Nihad Abbasov committed
41
    "theme_id": 1
42
    "color_scheme_id": 3
Nihad Abbasov's avatar
Nihad Abbasov committed
43 44 45 46
  }
]
```

47

Nihad Abbasov's avatar
Nihad Abbasov committed
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
## Single user

Get a single user.

```
GET /users/:id
```

Parameters:

+ `id` (required) - The ID of a user

```json
{
  "id": 1,
63
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
64 65
  "email": "john@example.com",
  "name": "John Smith",
66
  "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
67 68 69 70 71
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
72 73
  "extern_uid": "john.smith",
  "provider": "provider_name",
Nihad Abbasov's avatar
Nihad Abbasov committed
74
  "theme_id": 1
75
  "color_scheme_id": 2
Nihad Abbasov's avatar
Nihad Abbasov committed
76 77 78
}
```

79

80
## User creation
81 82

Creates a new user. Note only administrators can create new users.
83 84 85 86 87 88 89

```
POST /users
```

Parameters:

90 91 92 93 94 95 96 97 98 99 100 101
+ `email` (required)          - Email
+ `password` (required)       - Password
+ `username` (required)       - Username
+ `name` (required)           - Name
+ `skype` (optional)          - Skype ID
+ `linkedin` (optional)       - Linkedin
+ `twitter` (optional)        - Twitter account
+ `projects_limit` (optional) - Number of projects user can create
+ `extern_uid` (optional)     - External UID
+ `provider` (optional)       - External provider name
+ `bio` (optional)            - User's bio

102

103
## User modification
104 105

Modifies an existing user. Only administrators can change attributes of a user.
106 107 108 109 110 111

```
PUT /users/:id
```

Parameters:
112

113 114 115 116 117 118 119
+ `email`                             - Email
+ `username`                          - Username
+ `name`                              - Name
+ `password`                          - Password
+ `skype`                             - Skype ID
+ `linkedin`                          - Linkedin
+ `twitter`                           - Twitter account
Kevin Lyda's avatar
Kevin Lyda committed
120
+ `projects_limit`                    - Limit projects each user can create
121 122 123 124
+ `extern_uid`                        - External UID
+ `provider`                          - External provider name
+ `bio`                               - User's bio

125
Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
126
be more appropriate, e.g. when renaming the email address to some existing one.
127 128 129


## User deletion
130 131 132 133

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.
134 135 136 137 138

```
DELETE /users/:id
```

139 140 141 142
Parameters:

+ `id` (required) - The ID of the user

143

Nihad Abbasov's avatar
Nihad Abbasov committed
144 145
## Current user

146
Gets currently authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
147 148 149 150 151 152 153 154

```
GET /user
```

```json
{
  "id": 1,
155
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
156 157
  "email": "john@example.com",
  "name": "John Smith",
Alex Denisov's avatar
Alex Denisov committed
158
  "private_token": "dd34asd13as",
159
  "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
160 161 162 163 164 165
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "theme_id": 1
166
  "color_scheme_id": 2
Alex Denisov's avatar
Alex Denisov committed
167 168 169 170
  "is_admin": false,
  "can_create_group" : true,
  "can_create_team" : true,
  "can_create_project" : true
Nihad Abbasov's avatar
Nihad Abbasov committed
171 172
}
```
173

174

175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
## List SSH keys

Get a list of currently authenticated user's SSH keys.

```
GET /user/keys
```

```json
[
  {
    "id": 1,
    "title" : "Public key"
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  },
  {
    "id": 3,
    "title" : "Another Public key"
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
  }
]
```

202 203 204 205 206
Parameters:

+ **none**


207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
## Single SSH key

Get a single key.

```
GET /user/keys/:id
```

Parameters:

+ `id` (required) - The ID of an SSH key

```json
{
  "id": 1,
  "title" : "Public key"
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
}
```
228 229


230 231
## Add SSH key

232
Creates a new key owned by the currently authenticated user.
233 234 235 236 237 238 239 240 241 242 243

```
POST /user/keys
```

Parameters:

+ `title` (required) - new SSH Key's title
+ `key` (required) - new SSH key


244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
## Add SSH key for user

Create new key owned by specified user. Available only for admin

```
POST /users/:id/keys
```

Parameters:

+ `id` (required) - id of specified user
+ `title` (required) - new SSH Key's title
+ `key` (required) - new SSH key

Will return created key with status `201 Created` on success, or `404 Not
found` on fail.

261 262
## Delete SSH key

263 264
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`.
265 266 267 268 269 270 271 272 273

```
DELETE /user/keys/:id
```

Parameters:

+ `id` (required) - SSH key ID