]> git.defcon.no Git - hermes/blob - doc/api-nodes.txt
Forgot one instance of 'permitedcalls' ...
[hermes] / doc / api-nodes.txt
1 General description on API protocol:
2 =========================================================================
3 All API nodes currently use POST requests for all parameters.
4 All API nodes return JSON data unless explicitly noted ,
5 and all JSON results will contain a 'response' element.
6 The 'response' may be set to:
7 * 'ok' on success. Further contents depend on the node requested.
8 * 'invalid' on invalid requests. A 'cause' element should give a
9 keyword denoting what was invalid about the request...
10 * 'failed' on simple failure. A 'cause' element is supplied, with a
11 failure-keyword (e.g. 'nonexistant', 'inuse', 'dbfail').
12 A final 'detail' is commonly included, with a verbose desctiption.
13 * 'error' on critical failure. Regard this as a soft form of "500 server error"...
14
15 So, in all Return-specifications it should be assumed that 'response' is set to
16 'ok' on success.
17
18
19 Authentication mechanism:
20 =========================================================================
21 All API nodes except 'auth/login' and 'auth/logout' require a
22 'token authentication' based on a session identifier (session) and a
23 session authentication key (auth_key) passed as parameters.
24
25 The 'session' and 'auth_key' values are provided as response to a
26 successful API login through 'auth/login', and must be included as
27 parameters to all subsequent calls to the API.
28
29 The 'auth_key' has a limited lifetime (configurabel, defaul 5 minutes),
30 significantly shorter than the session lifetime. The 'auth_kye' must
31 be renewed before the key lifetime expires, by issuing a call to
32 'auth/ping'. The ping call will provide a new key that replaces the
33 previous 'auth_key' in subsequent calls to the API.
34
35 API login may be done using either a username/password combination,
36 or using a registered API key tied to the host originating the requests.
37
38 See documentation for nodes under 'auth/*' for information about
39 adding, removing and maintaining authentication users and keys.
40
41 Sample session:
42
43 call auth/login with username and password
44 store session and auth_key for further requests
45
46 perform API calls with session and auth_key set
47 ...
48
49 call auth/ping with session and auth_key set
50 update the auth_key used for requests
51
52 perform API calls with session and auth_key set
53 ...
54
55 call auth/logout with session set
56
57 NOTE: that the API also requires COOKIE-support in the user-agent
58 used to communicate with the API.
59
60 NOTE: See README for information on configuring API authentication
61 backends, and boostrapping the user/key authorizations.
62
63 Parameter notes:
64 =========================================================================
65 'user'/'alias' parameters marked '*' may alternatively be given as
66 username=foo + domain=bar
67 alias_username=foo + alias_domain=bar
68
69 List of API nodes:
70 =========================================================================
71
72 auth/login
73 -------------------
74 Required:
75 username=authuser
76 password=authpassword
77 Alternate:
78 api_key=API_KEY
79
80 Description:
81 TODO: DOCUMENT THIS.
82
83 Return:
84 Returns 'session' set to the allocated session_name and 'auth_key'
85 set to the generated auth_key. These must be used for further access,
86 and the key must be refreshed through 'auth/ping' at intervals.
87 Returns 'failed' with 'cause' = 'unauthorized' if Login failed
88
89 auth/logout
90 -------------------
91 Required:
92 session=session_name
93
94 Description:
95 TODO: DOCUMENT THIS.
96 // De-authenticate/deauthorize the ongoing session.
97 // I.e. destroy session data, remove session cookies.
98
99 Return:
100 Returns 'ok' on successful logout
101
102 auth/ping
103 -------------------
104 Required:
105 session=$session_name
106 auth_key=$auth_key
107
108 Description:
109 TODO: DOCUMENT THIS.
110 // API clients are required to periodically ping the server
111 // The time between pings (interval) is 5 minutes?
112 // A ping call refreshes cookie lifetimes, then
113 // generates and stores a new auth_key
114 // The ping required a valid session...
115 // A successful ping returns a 'response' => 'pong'
116 // along with the new auth_key.
117
118 NOTE!: Does not give 'response' => 'ok' !
119
120 Return:
121 Returns 'pong' with 'auth_key' set to the new key to be used
122 with the session_name in further requests.
123
124 auth/new_apikey
125 -------------------
126 Required:
127 host_ip=10.20.30.40
128 access=limited_read
129
130 Description:
131 TODO: DOCUMENT THIS.
132 'access' may be one of:
133 * limited_read
134 * full_read
135 * read_write
136
137 Return:
138 Returns 'key', 'host' and 'access'.
139 Returns 'invalid' with 'cause' = 'parameters' on parameter error
140 Returns 'failed' with 'cause' = 'error' on database errors.
141 TODO: Change 'error' to 'dbfail'.
142
143 auth/remove_apikey
144 -------------------
145 Required:
146 api_key=$key
147
148 Description:
149 TODO: DOCUMENT THIS.
150
151 Return:
152 Returns 'key' set to the removed key on success.
153 Returns 'invalid' on parameter error
154 Returns 'failed' with 'cause' = 'nonexistant' if key does not exist.
155 Returns 'failed' with 'cause' = 'error' on database errors.
156 TODO: Change 'error' to 'dbfail'.
157
158 auth/list_apikeys
159 -------------------
160
161 Description:
162 TODO: DOCUMENT THIS.
163
164 Return:
165 Returns 'list'
166
167 auth/authorize_user
168 -------------------
169 Required:
170 username=authuser
171 access=limited_read
172
173 Description:
174 TODO: DOCUMENT THIS.
175 // Add or update a valid back-end user in authorization
176 // if the current authentication has write access.
177 // If the authorization does not exist, add it.
178 // If the user is already authorized, replace access level.
179
180 'access' may be one of:
181 * limited_read
182 * full_read
183 * read_write
184
185 Return:
186 Returns 'user' and 'access' when user was successfully added.
187 Returns 'invalid' with 'cause' = 'parameters' on parameter error
188 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
189 Returns 'failed' with 'cause' = 'error' on database errors.
190
191 auth/remove_user
192 -------------------
193 Required:
194 username=authuser
195
196 Description:
197 TODO: DOCUMENT THIS.
198 // If the current authentication has write access:
199 // Remove authorization for the given users.
200 // Delete user from backend if backend is read-write.
201
202 Return:
203 Returns 'user' when user was successfully removed.
204 Returns 'invalid' with 'cause' = 'parameters' on parameter error
205 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
206 Returns 'failed' with 'cause' = 'error' on database errors.
207
208 auth/list_users
209 -------------------
210
211 Description:
212 Returns 'list'
213
214 auth/add_user
215 -------------------
216
217 Description:
218 TODO: This is not implemented. Document, write test and implement.
219 Returns 'notimplemented'
220 // Add user to backend if backend is read-write and
221 // the current authentication has write access.
222 // The created user should be added to authorizations
223 // with an access level of "limited_read (1)"
224
225 auth/update_user
226 -------------------
227
228 Description:
229 TODO: This is not implemented. Document, write test and implement.
230 Returns 'notimplemented'
231 // Update the given user in the backend, if the backend
232 // is read-write, and the current authentication has
233 // write access.
234
235 user/get
236 -------------------
237 Required:
238 user=user@bar.bz *
239
240 Description:
241 Return User information, not including hardphone association.
242
243 Return:
244 On success, 'user' will be set to the user-data set:
245 for all users:
246 type,username,password,domain,authid,registrar,
247 r_port,proxy,p_port,dialplan,displayname,linetext
248 for local users (kamailio), as above, plus:
249 email,ha1,ha1b,rpid,permittedcalls
250 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
251 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
252
253 user/list
254 -------------------
255 Optional:
256 search=foo@bar
257
258 Description:
259 Return an array of users, with 'user' set to SIP-address and
260 'displayname' set to the users Displayname.
261
262 If the search parameter is included, a globbing search is performed,
263 and only matches are listed.
264
265 Return:
266 TODO: Document this
267
268 user/add_local
269 -------------------
270 Required:
271 user=foo@bar.bz *
272 displayname=baz
273 email=qux@zef.tld
274
275 Description:
276 Adds a user account to both Kamailio and provisioning, if the
277 username@domain is nonexistant, and the domain is local (handled by
278 Kamailio). The password for the user is auto-generated.
279
280 Return:
281 Returns a full user object, the same form as user/get
282 Returns 'failed' with 'cause' = 'exists' if address is taken
283 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
284 Returns 'failed' with 'cause' = 'servfail' if no default servers
285 could be determined for the requested domain. See domain/set_servers.
286 Returns 'failed' with 'cause' = 'dbfail' on database errors..
287
288 user/add_remote
289 -------------------
290 Required:
291 user=foo@bar.bz *
292 password=S3cr3t
293 displayname=baz
294 registrar=sip.example.com
295 Optional:
296 r_port=5060
297 proxy=sipproxy.example.com
298 p_port=5060
299 authid=realfoo
300 dialplan=(.*)
301 linetext=lalala
302
303 Description:
304 Adds a provisioning user for a remote SIP account. This allows locally
305 provisioned hardphones to be associated with non-local SIP accounts.
306
307 Return:
308 Returns a full user object, the same form as user/get
309 Returns 'failed' with 'cause' = 'domain' if an attempt is made to
310 add_remote for a local domain.
311 Returns 'failed' with 'cause' = 'exists' on any address collisions
312 Returns 'failed' with 'cause' = 'dbfail' on database errors..
313
314 user/remove
315 -------------------
316 Required:
317 user=foo@bar.bz *
318
319 Description:
320 Removes user account from Kamailio, if present, and removes user from
321 provisioning.
322
323 Will fail if user has associated hardphones, remove phones before
324 removing user.
325
326 TODO: Should fail if user has associated aliases. Remove aliases before
327 removing user.
328
329 Return:
330 TODO: Document additional data on 'result' = 'ok'
331 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
332 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
333 Returns 'failed' with 'cause' = 'inuse' if phone-associations exists
334 TODO: Returns 'failed' with 'cause' = 'inuse' if aliases exist for the address
335
336
337 user/change_pw
338 -------------------
339 Required:
340 user=foo@bar.bz *
341 password=baz
342
343 Description:
344 Changes the password for the given user, returns 'ok' with 'detail' as
345 a descriptive text on success. In the current implementation,
346 provisioning and kamailio passwords are handled separately, so one
347 may succeed and the other fail. As is, this permits password changes
348 of non-local provision users with minimal effort.
349
350 Return:
351 Returns 'detail' on success.
352 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
353 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
354 Returns 'failed' with 'cause' = 'dbfail' if the database request
355 failed. Note that this may be because the given password was identical
356 to the old.
357
358 user/change_email
359 -------------------
360 Required:
361 user=foo@bar.bz *
362 email=user@example.com
363
364 Description:
365 Changes the email address for the given user, returns 'ok' with
366 'user' set to the requested username and 'email' set to the
367 email address. This only applies to kamailio local users.
368
369 Return:
370 Returns 'user' and 'email' on success.
371 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
372 TODO: Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
373 Returns 'failed' with 'cause' = 'dbfail' if the database request
374 failed. This may be because no update was required ...
375
376 user/update
377 -------------------
378 Required:
379 user=foo@bar.bz *
380 optionals:
381 displayname=baz
382 dialplan=(.*)
383 linetext=lalala
384 email=foo@bar.baz
385
386 Updates user with the given data....
387 TODO: Extend this description ;)
388
389 Return:
390 Returns two arrays on success, 'updated' containing updated params
391 and 'skipped' containing specified parameters that did not require
392 any changes.
393 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
394 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
395 Returns 'failed' with 'cause' = 'dbfail' if the database request
396 failed. With database errors, the array 'failed' will contain any
397 parameters that may have caused the dbfail.
398
399 user/available
400 -------------------
401 user=foo@bar.bz *
402
403 Description:
404 Tests an address to see if it is available.
405
406 Return:
407 Returns 'ok' with 'cause' = 'nonexistant' if the address is available.
408 TODO: Returns 'failed' with 'cause' = 'domain' if the domain is not a kamailio domain.
409 Returns 'failed' with 'cause' = 'exists' if the address is in use.
410 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
411
412 user/gen_pw
413 -------------------
414
415 Description:
416 Generates a random password on the same form as that used by
417 user/add_local.
418
419 NOTE: This node does not use JSON formatting.
420
421 Return:
422 Return is always a password in plain text, with no formatting.
423
424 phone/get
425 -------------------
426 Optional:
427 mac=f00ba2ba5c00
428 user=foo@bar.bz *
429
430 Description:
431 Returns a list of associated elements. If MAC address is given as
432 parameter, a list of associated user@domain addresses is retruned. If
433 user@domain is given as parameter, a list of associated mac addresses
434 is returned.
435
436 Return:
437 Returns 'list' as an array of phone-user mappings on success,
438 where each element of 'list' consists of either usernames or mac-adresses.
439 Returns 'failed' with 'cause' = 'nonexistant' on no matches.
440 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
441
442 phone/list
443 -------------------
444 Optional:
445 search=f00ba2
446
447 Description:
448 Returns the list of registered MAC addresses. If the (optional) search
449 parameter is included, the list is the result of a globbing search,
450 a subset matching on the MAC addresses.
451
452 Return:
453 Returns 'list' as a simple array of registered MAC-adresses on success,
454 the list will be limited to addresses matching the search if provided.
455
456
457 phone/add
458 -------------------
459 Required:
460 user=foo@bar.bz *
461 mac=f00ba2ba5c00
462
463 Description:
464 Adds a phone-to-user association to Provisioning. The user may be
465 provided as 'username' and 'domain' in separate parameters, or as
466 'user' in sip-address form. The MAC address must be valid, in plain-hex
467 or colon-separated form, and the user must match a valid user
468 registration.
469
470 Return:
471 Returns 'mac', 'username' and 'domain' on success.
472 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
473 Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
474 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
475 Returns 'failed' with 'cause' = 'exists' if user+mac is already reg.
476 Returns 'failed' with 'cause' = 'dbfail' on database failure.
477
478 phone/remove
479 -------------------
480 Required:
481 user=foo@bar.bz *
482 mac=f00ba2ba5c00
483
484 Description:
485 Deletes a phone-to-user association. Required parameters and formats
486 are identical to the phone/add node.
487
488 Return:
489 Returns 'mac', 'username' and 'domain' on success.
490 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
491 Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
492 Returns 'failed' with 'cause' = 'nonexistant' on no such registration.
493
494
495 numbers/list
496 -------------------
497 Optional:
498 search=1234
499 random=true
500 limit=n
501
502 Description:
503 Gives a list of entries in the phone number pool.
504 With no parameters, the entire (ordered) list of available numbers is
505 returned. With 'search', the result of a pre-post globbing search is
506 returned With 'random', a list of entries is returned unordered (random
507 order) For all nodes, 'limit' may be a numeric limit of desired
508 results.
509
510 Return:
511 Returns the list of numbers as the array 'list'.
512 Returns 'failed' with 'cause' = 'empty' if no numbers were listed...
513
514 numbers/add_range
515 -------------------
516 Required:
517 start=+4712345000
518 end=+4712345678
519
520 Description:
521 The start and end must have identical lead-in, and start must be less
522 than end. Both numbers must be given in E164 format, remember to
523 urlencode the plus (+ -> %2B). The numeric component of both will be
524 extracted, and all numbers in the range will be iteratively added to
525 the pool, including the ending number.
526
527 Return:
528 TODO: Document additional info provided on 'result' = 'ok'
529 Returns 'failed' with 'cause' = 'rejected' with 'detail' set on failure
530
531 numbers/add
532 -------------------
533 Required:
534 number=+4712345679
535
536 Description:
537 Adds the given number to the pool, after verifying that the number is
538 in valid E164 format, and that the number does not already exist in the
539 pool.
540
541 Return:
542 Returns "Added <number>" in 'detail' on success.
543 Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
544 valid E164 number" if the provided number could not pass E164
545 validation.
546 Returns 'failed' with 'cause' = 'exists' if number is already in the pool.
547 TODO: Returns 'failed' with 'cause' = 'dbfail' on database failure.
548 TODO: Gives 'cause' = 'rejected' with no detail in current code.
549
550 numbers/remove
551 -------------------
552 Required:
553 number=+4712345676
554
555 Description:
556 Removes/pulls a number from the pool.
557 The number must be a valid e164 number, and must be present in the
558 pool.
559
560 Return:
561 Returns 'number' set to the number that was pulled from the pool.
562 Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
563 valid E164 number" if the provided number could not pass E164
564 validation.
565 Returns 'failed' with 'cause' = 'nonexistant' if number is not the pool.
566 Returns 'failed' with 'cause' = 'dbfail' on database failure.
567
568 numbers/inpool
569 -------------------
570 Required:
571 number=+4712345676
572
573 Description:
574 Tests if the given E164 number is in the pool.
575
576 Return:
577 Returns 'number' = '<number>' If the number is in the pool
578 Returns response = 'failed' with 'cause' = 'nonexistant' if not.
579
580 alias/list
581 -------------------
582 Optional:
583 alias=foo@bar.bz
584 destination=foo@bar.bz
585 e164=true
586
587 Description:
588 With no parameters, this will return all defined aliases (potentially a
589 huge list). With the destination parameter set, only aliases for that
590 destination will be listed, and with the e164 option set to true, only
591 an e164 alias will be returned (if one/it exists). The alias parameter
592 gives the same behaviour, but looks up an alias address instead of the
593 destination. The e164 option is not valid for the alias search
594 (naturally).
595
596 Return:
597 Returns 'ok' on success, with an array 'aliases' containing
598 'destination' and 'alias' pairs.
599 Returns 'ok' with an empty array if the search gave no results.
600 Returns 'ok' with an empty array if the database search fails.
601 Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
602
603 alias/add
604 -------------------
605 Required:
606 alias=foo@bar.bz *
607 destination=bar@qux.zx
608
609 Description:
610 Add an alias specified by alias_username and alias_domain that
611 points to the destination SIP-adress.
612
613 Return:
614 On success, 'ok' is returned, with 'alias' and 'destination' set to the
615 resulting alias and destination adresses.
616 Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
617 resulting alias-adress or destination are invalid SIP-adresses.
618 Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
619 not a Kamailio domain.
620 Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
621 and the user already has an E164 alias registered.
622 Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
623 domain is requested, but the local subscriber does not exist.
624 Returns 'failed' with 'cause' = 'exists' for aliases that already
625 exists, (and aliases that overlaps SIP-accounts - not implemented).
626
627
628 alias/remove
629 -------------------
630 Required:
631 alias=foo@bar.bz *
632
633 Description:
634 Removes the alias given by alias_username and alias_domain.
635
636 Return:
637 Returns 'ok' with the removed alias adress as 'alias' on success
638 Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
639 exists.
640 Returns 'invalid' with 'cause' = 'address' if the given alias is not a
641 valid SIP adress.
642
643
644 domain/list
645 -------------------
646
647 Description:
648 Returns a list of configured and valid domains. May return an empty
649 list if no domains are configured for kamailio. No node is provided
650 to add domains, this is not a task for Hermes, but a kamailio
651 configuration task.
652
653 Return:
654 Returns a list of domains as 'list' on success.
655 Returns 'failed' on database errors.
656
657 domain/get_servers
658 -------------------
659 Required:
660 domain=bar.bz
661
662 Description:
663 Provides the default registrar/proxy/provisioning server information
664 for the given domain.
665
666 Return:
667 Returns 'ok' with 'servers' set to a kvp-set on success, containing:
668 'registrar','r_port','proxy','p_port','prov_url'.
669 Returns 'failed' with 'cause' = 'nonexistant' if lookup of data for
670 given domain results in an empty set (not configured).
671
672 domain/set_servers
673 -------------------
674 Required:
675 domain=bar.bz
676 registrar=server.bar.bz
677 r_port=5060
678 proxy=proxy.bar.bz
679 p_port=5060
680 prov_url=http://server.bar.bz/hermes/prov
681
682 Description:
683 Sets the server data for the given domain. All of these parameters
684 are Required: 'domain', 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'.
685 If no default server data is defined, the configuration is added.
686 If server configuration existed, the default data is updated.
687
688 Return:
689 Returns 'ok' with 'servers' set as domain/get_servers on success.
690 Returns 'failed' with 'cause' set to 'cause' set to 'parameters'
691 if one of these is true:
692 * Missing parameters
693 * One or more NULL/empty parameters
694 * Non-numeric values for port-numbers.
695 If you need to determine which of these triggered, the
696 'description' contains a text describing the actual fail.
697 Return 'failed' with 'cause' = 'error' on database failure.
698
699 BUGS:
700 ---------------------
701
702 api/alias/list destination=foo@bar.bz e164=true
703 should return an empty array, returns false
704
705 TODO list:
706 ---------------------
707
708 Some TODO's listed above ...
709
710 Permissions! (user/permissions?user=...)
711 The permissions bit-flag seems to be:
712 NOCALLS 1
713 EMERGENCY 2
714 INTERNAL 4
715 VOIP 8
716 NATIONAL 16
717 SERVICES 32
718 INTERNATIONAL 64
719 OTHERS 128
720
721 can_write() checks!
722 can_read_full() checks!
723
724 Improve robustness of change_pw: fetch old password for rollback/testing.
725
726 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
727
728 Perform an evaluation of the security related to the api-key functionality,
729 and replace if the method is evaluated as too weak. I.e. implement strong
730 non-interactive, non-user based authentication.