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"...
15 So, in all Return-specifications it should be assumed that 'response' is set to
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.
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.
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.
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.
38 See documentation for nodes under 'auth/*' for information about
39 adding, removing and maintaining authentication users and keys.
43 call auth/login with username and password
44 store session and auth_key for further requests
46 perform API calls with session and auth_key set
49 call auth/ping with session and auth_key set
50 update the auth_key used for requests
52 perform API calls with session and auth_key set
55 call auth/logout with session set
57 NOTE: that the API also requires COOKIE-support in the user-agent
58 used to communicate with the API.
60 NOTE: See README for information on configuring API authentication
61 backends, and boostrapping the user/key authorizations.
64 =========================================================================
65 'user'/'alias' parameters marked '*' may alternatively be given as
66 username=foo + domain=bar
67 alias_username=foo + alias_domain=bar
70 =========================================================================
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
96 // De-authenticate/deauthorize the ongoing session.
97 // I.e. destroy session data, remove session cookies.
100 Returns 'ok' on successful logout
105 session=$session_name
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.
118 NOTE!: Does not give 'response' => 'ok' !
121 Returns 'pong' with 'auth_key' set to the new key to be used
122 with the session_name in further requests.
132 'access' may be one of:
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'.
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'.
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.
180 'access' may be one of:
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.
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.
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.
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)"
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
241 Return User information, not including hardphone association.
244 On success, 'user' will be set to the user-data set:
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.
259 Return registered user agent locations for a given user, with
260 contact and user agent information.
263 On success, returns the array 'locations', each element contianing:
264 'contact' is the registration contact (the location)
265 'useragent' is the UA string from the client
266 'expires' is the expiration time of the registration, as unix timestamp
268 Returns 'failed' with 'cause' = 'offline' if user is not registered ...
269 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
272 Add a return code for non-existant subscriber?
280 Return an array of users, with 'user' set to SIP-address and
281 'displayname' set to the users Displayname.
283 If the search parameter is included, a globbing search is performed,
284 and only matches are listed.
297 Adds a user account to both Kamailio and provisioning, if the
298 username@domain is nonexistant, and the domain is local (handled by
299 Kamailio). The password for the user is auto-generated.
302 Returns a full user object, the same form as user/get
303 Returns 'failed' with 'cause' = 'exists' if address is taken
304 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
305 Returns 'failed' with 'cause' = 'servfail' if no default servers
306 could be determined for the requested domain. See domain/set_servers.
307 Returns 'failed' with 'cause' = 'dbfail' on database errors..
315 registrar=sip.example.com
318 proxy=sipproxy.example.com
325 Adds a provisioning user for a remote SIP account. This allows locally
326 provisioned hardphones to be associated with non-local SIP accounts.
329 Returns a full user object, the same form as user/get
330 Returns 'failed' with 'cause' = 'domain' if an attempt is made to
331 add_remote for a local domain.
332 Returns 'failed' with 'cause' = 'exists' on any address collisions
333 Returns 'failed' with 'cause' = 'dbfail' on database errors..
341 Removes user account from Kamailio, if present, and removes user from
344 Will fail if user has associated hardphones, remove phones before
347 TODO: Should fail if user has associated aliases. Remove aliases before
351 TODO: Document additional data on 'result' = 'ok'
352 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
353 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
354 Returns 'failed' with 'cause' = 'inuse' if phone-associations exists
355 TODO: Returns 'failed' with 'cause' = 'inuse' if aliases exist for the address
365 Changes the password for the given user, returns 'ok' with 'detail' as
366 a descriptive text on success. In the current implementation,
367 provisioning and kamailio passwords are handled separately, so one
368 may succeed and the other fail. As is, this permits password changes
369 of non-local provision users with minimal effort.
372 Returns 'detail' on success.
373 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
374 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
375 Returns 'failed' with 'cause' = 'dbfail' if the database request
376 failed. Note that this may be because the given password was identical
383 email=user@example.com
386 Changes the email address for the given user, returns 'ok' with
387 'user' set to the requested username and 'email' set to the
388 email address. This only applies to kamailio local users.
391 Returns 'user' and 'email' on success.
392 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
393 TODO: Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
394 Returns 'failed' with 'cause' = 'dbfail' if the database request
395 failed. This may be because no update was required ...
407 Updates user with the given data....
408 TODO: Extend this description ;)
411 Returns two arrays on success, 'updated' containing updated params
412 and 'skipped' containing specified parameters that did not require
414 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
415 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
416 Returns 'failed' with 'cause' = 'dbfail' if the database request
417 failed. With database errors, the array 'failed' will contain any
418 parameters that may have caused the dbfail.
425 Tests an address to see if it is available.
428 Returns 'ok' with 'cause' = 'nonexistant' if the address is available.
429 TODO: Returns 'failed' with 'cause' = 'domain' if the domain is not a kamailio domain.
430 Returns 'failed' with 'cause' = 'exists' if the address is in use.
431 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
437 Generates a random password on the same form as that used by
440 NOTE: This node does not use JSON formatting.
443 Return is always a password in plain text, with no formatting.
452 Returns a list of associated elements. If MAC address is given as
453 parameter, a list of associated user@domain addresses is retruned. If
454 user@domain is given as parameter, a list of associated mac addresses
458 Returns 'list' as an array of phone-user mappings on success,
459 where each element of 'list' consists of either usernames or mac-adresses.
460 Returns 'failed' with 'cause' = 'nonexistant' on no matches.
461 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
469 Returns the list of registered MAC addresses. If the (optional) search
470 parameter is included, the list is the result of a globbing search,
471 a subset matching on the MAC addresses.
474 Returns 'list' as a simple array of registered MAC-adresses on success,
475 the list will be limited to addresses matching the search if provided.
485 Adds a phone-to-user association to Provisioning. The user may be
486 provided as 'username' and 'domain' in separate parameters, or as
487 'user' in sip-address form. The MAC address must be valid, in plain-hex
488 or colon-separated form, and the user must match a valid user
492 Returns 'mac', 'username' and 'domain' on success.
493 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
494 Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
495 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
496 Returns 'failed' with 'cause' = 'exists' if user+mac is already reg.
497 Returns 'failed' with 'cause' = 'dbfail' on database failure.
506 Deletes a phone-to-user association. Required parameters and formats
507 are identical to the phone/add node.
510 Returns 'mac', 'username' and 'domain' on success.
511 Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
512 Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
513 Returns 'failed' with 'cause' = 'nonexistant' on no such registration.
524 Gives a list of entries in the phone number pool.
525 With no parameters, the entire (ordered) list of available numbers is
526 returned. With 'search', the result of a pre-post globbing search is
527 returned With 'random', a list of entries is returned unordered (random
528 order) For all nodes, 'limit' may be a numeric limit of desired
532 Returns the list of numbers as the array 'list'.
533 Returns 'failed' with 'cause' = 'empty' if no numbers were listed...
542 The start and end must have identical lead-in, and start must be less
543 than end. Both numbers must be given in E164 format, remember to
544 urlencode the plus (+ -> %2B). The numeric component of both will be
545 extracted, and all numbers in the range will be iteratively added to
546 the pool, including the ending number.
549 TODO: Document additional info provided on 'result' = 'ok'
550 Returns 'failed' with 'cause' = 'rejected' with 'detail' set on failure
558 Adds the given number to the pool, after verifying that the number is
559 in valid E164 format, and that the number does not already exist in the
563 Returns "Added <number>" in 'detail' on success.
564 Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
565 valid E164 number" if the provided number could not pass E164
567 Returns 'failed' with 'cause' = 'exists' if number is already in the pool.
568 TODO: Returns 'failed' with 'cause' = 'dbfail' on database failure.
569 TODO: Gives 'cause' = 'rejected' with no detail in current code.
577 Removes/pulls a number from the pool.
578 The number must be a valid e164 number, and must be present in the
582 Returns 'number' set to the number that was pulled from the pool.
583 Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
584 valid E164 number" if the provided number could not pass E164
586 Returns 'failed' with 'cause' = 'nonexistant' if number is not the pool.
587 Returns 'failed' with 'cause' = 'dbfail' on database failure.
595 Tests if the given E164 number is in the pool.
598 Returns 'number' = '<number>' If the number is in the pool
599 Returns response = 'failed' with 'cause' = 'nonexistant' if not.
605 destination=foo@bar.bz
609 With no parameters, this will return all defined aliases (potentially a
610 huge list). With the destination parameter set, only aliases for that
611 destination will be listed, and with the e164 option set to true, only
612 an e164 alias will be returned (if one/it exists). The alias parameter
613 gives the same behaviour, but looks up an alias address instead of the
614 destination. The e164 option is not valid for the alias search
618 Returns 'ok' on success, with an array 'aliases' containing
619 'destination' and 'alias' pairs.
620 Returns 'ok' with an empty array if the search gave no results.
621 Returns 'ok' with an empty array if the database search fails.
622 Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
628 destination=bar@qux.zx
631 Add an alias specified by alias_username and alias_domain that
632 points to the destination SIP-adress.
635 On success, 'ok' is returned, with 'alias' and 'destination' set to the
636 resulting alias and destination adresses.
637 Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
638 resulting alias-adress or destination are invalid SIP-adresses.
639 Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
640 not a Kamailio domain.
641 Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
642 and the user already has an E164 alias registered.
643 Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
644 domain is requested, but the local subscriber does not exist.
645 Returns 'failed' with 'cause' = 'exists' for aliases that already
646 exists, (and aliases that overlaps SIP-accounts - not implemented).
655 Removes the alias given by alias_username and alias_domain.
658 Returns 'ok' with the removed alias adress as 'alias' on success
659 Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
661 Returns 'invalid' with 'cause' = 'address' if the given alias is not a
669 Returns a list of configured and valid domains. May return an empty
670 list if no domains are configured for kamailio. No node is provided
671 to add domains, this is not a task for Hermes, but a kamailio
675 Returns a list of domains as 'list' on success.
676 Returns 'failed' on database errors.
684 Provides the default registrar/proxy/provisioning server information
685 for the given domain.
688 Returns 'ok' with 'servers' set to a kvp-set on success, containing:
689 'registrar','r_port','proxy','p_port','prov_url'.
690 Returns 'failed' with 'cause' = 'nonexistant' if lookup of data for
691 given domain results in an empty set (not configured).
697 registrar=server.bar.bz
701 prov_url=http://server.bar.bz/hermes/prov
704 Sets the server data for the given domain. All of these parameters
705 are Required: 'domain', 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'.
706 If no default server data is defined, the configuration is added.
707 If server configuration existed, the default data is updated.
710 Returns 'ok' with 'servers' set as domain/get_servers on success.
711 Returns 'failed' with 'cause' set to 'cause' set to 'parameters'
712 if one of these is true:
714 * One or more NULL/empty parameters
715 * Non-numeric values for port-numbers.
716 If you need to determine which of these triggered, the
717 'description' contains a text describing the actual fail.
718 Return 'failed' with 'cause' = 'error' on database failure.
726 Gets the permissions value for a user, with no parsing.
727 The permission system is based on bit-flags, with the following values:
736 The user must match a valid user registration.
739 Returns 'permission' set to the applied permission value on success.
740 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
741 Returns 'failed' with 'cause' = 'dbfail' on database failure.
751 Sets the permissions value for a user directly. The permission
752 system is based on bit-flags, with the following values:
761 To give a subscriber full permissions, set permission to 255.
762 To give a subscriber National calls, all internal and VOIP
763 calls, but not international, sat-phones and other, use 63.
764 To give a user emergency and internal, but no other calls,
765 the permission value becomes 7.
766 The user must match a valid user registration.
769 Returns 'permission' set to the applied permission value on success.
770 Returns 'failed' with 'cause' = 'dbfail' on database failure.
774 ---------------------
776 api/alias/list destination=foo@bar.bz e164=true
777 should return an empty array, returns false
780 ---------------------
782 user/forward To set up permanent forwarding. Call forward is stored as a user
783 preference value in the kamailio database. Evample of diverting calls to
784 'jonl@hig.no' to the number +4761135280':
785 insert into usr_preferences (username, domain, attribute, value, last_modified) values ( 'jonl', 'hig.no', 'cfu', '+4761135280', now());
787 Some TODO's listed above ...
789 Permissions! (user/permissions?user=...)
790 The permissions bit-flag seems to be:
801 can_read_full() checks!
803 Improve robustness of change_pw: fetch old password for rollback/testing.
805 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
807 Perform an evaluation of the security related to the api-key functionality,
808 and replace if the method is evaluated as too weak. I.e. implement strong
809 non-interactive, non-user based authentication.