git.defcon.no Git - hermes/blob - 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/location
 254 -------------------
 255   Required:
 256         user=user@bar.bz *
 257
 258   Description:
 259         Return registered user agent locations for a given user, with
 260         contact and user agent information.
 261
 262   Return:
 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
 267
 268         Returns 'failed' with 'cause' = 'offline' if user is not registered ...
 269         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 270
 271   TODO:
 272         Add a return code for non-existant subscriber?
 273
 274 user/list
 275 -------------------
 276   Optional:
 277         search=foo@bar
 278
 279   Description:
 280         Return an array of users, with 'user' set to SIP-address and
 281         'displayname' set to the users Displayname.
 282
 283         If the search parameter is included, a globbing search is performed,
 284         and only matches are listed.
 285
 286   Return:
 287         TODO: Document this
 288
 289 user/add_local
 290 -------------------
 291   Required:
 292         user=foo@bar.bz *
 293         displayname=baz
 294         email=qux@zef.tld
 295
 296   Description:
 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.
 300
 301   Return:
 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..
 308
 309 user/add_remote
 310 -------------------
 311   Required:
 312         user=foo@bar.bz *
 313         password=S3cr3t
 314         displayname=baz
 315         registrar=sip.example.com
 316   Optional:
 317         r_port=5060
 318         proxy=sipproxy.example.com
 319         p_port=5060
 320         authid=realfoo
 321         dialplan=(.*)
 322         linetext=lalala
 323
 324   Description:
 325         Adds a provisioning user for a remote SIP account. This allows locally
 326         provisioned hardphones to be associated with non-local SIP accounts.
 327
 328   Return:
 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..
 334
 335 user/remove
 336 -------------------
 337   Required:
 338         user=foo@bar.bz *
 339
 340   Description:
 341         Removes user account from Kamailio, if present, and removes user from
 342         provisioning.
 343
 344         Will fail if user has associated hardphones, remove phones before
 345         removing user.
 346
 347         TODO: Should fail if user has associated aliases. Remove aliases before
 348         removing user.
 349
 350   Return:
 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
 356
 357
 358 user/change_pw
 359 -------------------
 360   Required:
 361         user=foo@bar.bz *
 362         password=baz
 363
 364   Description:
 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.
 370
 371   Return:
 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
 377         to the old.
 378
 379 user/change_email
 380 -------------------
 381   Required:
 382         user=foo@bar.bz *
 383         email=user@example.com
 384
 385   Description:
 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.
 389
 390   Return:
 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 ...
 396
 397 user/update
 398 -------------------
 399   Required:
 400         user=foo@bar.bz *
 401   optionals:
 402         displayname=baz
 403         dialplan=(.*)
 404         linetext=lalala
 405         email=foo@bar.baz
 406
 407         Updates user with the given data....
 408         TODO: Extend this description ;)
 409
 410   Return:
 411         Returns two arrays on success, 'updated' containing updated params
 412         and 'skipped' containing specified parameters that did not require
 413         any changes.
 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.
 419
 420 user/available
 421 -------------------
 422         user=foo@bar.bz *
 423
 424   Description:
 425         Tests an address to see if it is available.
 426
 427   Return:
 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.
 432
 433 user/gen_pw
 434 -------------------
 435
 436   Description:
 437         Generates a random password on the same form as that used by
 438         user/add_local.
 439
 440         NOTE: This node does not use JSON formatting.
 441
 442   Return:
 443         Return is always a password in plain text, with no formatting.
 444
 445 phone/get
 446 -------------------
 447   Optional:
 448         mac=f00ba2ba5c00
 449         user=foo@bar.bz *
 450
 451   Description:
 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
 455         is returned.
 456
 457   Return:
 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.
 462
 463 phone/list
 464 -------------------
 465   Optional:
 466         search=f00ba2
 467
 468   Description:
 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.
 472
 473   Return:
 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.
 476
 477
 478 phone/add
 479 -------------------
 480   Required:
 481         user=foo@bar.bz *
 482         mac=f00ba2ba5c00
 483
 484   Description:
 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
 489         registration.
 490
 491   Return:
 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.
 498
 499 phone/remove
 500 -------------------
 501   Required:
 502         user=foo@bar.bz *
 503         mac=f00ba2ba5c00
 504
 505   Description:
 506         Deletes a phone-to-user association. Required parameters and formats
 507         are identical to the phone/add node.
 508
 509   Return:
 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.
 514
 515
 516 numbers/list
 517 -------------------
 518   Optional:
 519         search=1234
 520         random=true
 521         limit=n
 522
 523   Description:
 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
 529         results.
 530
 531   Return:
 532         Returns the list of numbers as the array 'list'.
 533         Returns 'failed' with 'cause' = 'empty' if no numbers were listed...
 534
 535 numbers/add_range
 536 -------------------
 537   Required:
 538         start=+4712345000
 539         end=+4712345678
 540
 541   Description:
 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.
 547
 548   Return:
 549         TODO: Document additional info provided on 'result' = 'ok'
 550         Returns 'failed' with 'cause' = 'rejected' with 'detail' set on failure
 551
 552 numbers/add
 553 -------------------
 554   Required:
 555         number=+4712345679
 556
 557   Description:
 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
 560         pool.
 561
 562   Return:
 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
 566         validation.
 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.
 570
 571 numbers/remove
 572 -------------------
 573   Required:
 574         number=+4712345676
 575
 576   Description:
 577         Removes/pulls a number from the pool.
 578         The number must be a valid e164 number, and must be present in the
 579         pool.
 580
 581   Return:
 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
 585         validation.
 586         Returns 'failed' with 'cause' = 'nonexistant' if number is not the pool.
 587         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 588
 589 numbers/inpool
 590 -------------------
 591   Required:
 592         number=+4712345676
 593
 594   Description:
 595         Tests if the given E164 number is in the pool.
 596
 597   Return:
 598         Returns 'number' = '<number>' If the number is in the pool
 599         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 600
 601 alias/list
 602 -------------------
 603   Optional:
 604         alias=foo@bar.bz
 605         destination=foo@bar.bz
 606         e164=true
 607
 608   Description:
 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
 615         (naturally).
 616
 617   Return:
 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.
 623
 624 alias/add
 625 -------------------
 626   Required:
 627         alias=foo@bar.bz *
 628         destination=bar@qux.zx
 629
 630   Description:
 631         Add an alias specified by alias_username and alias_domain that
 632         points to the destination SIP-adress.
 633
 634   Return:
 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).
 647
 648
 649 alias/remove
 650 -------------------
 651   Required:
 652         alias=foo@bar.bz *
 653
 654   Description:
 655         Removes the alias given by alias_username and alias_domain.
 656
 657   Return:
 658         Returns 'ok' with the removed alias adress as 'alias' on success
 659         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
 660         exists.
 661         Returns 'invalid' with 'cause' = 'address' if the given alias is not a
 662         valid SIP adress.
 663
 664
 665 domain/list
 666 -------------------
 667
 668   Description:
 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
 672         configuration task.
 673
 674   Return:
 675         Returns a list of domains as 'list' on success.
 676         Returns 'failed' on database errors.
 677
 678 domain/get_servers
 679 -------------------
 680   Required:
 681         domain=bar.bz
 682
 683   Description:
 684         Provides the default registrar/proxy/provisioning server information
 685         for the given domain.
 686
 687   Return:
 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).
 692
 693 domain/set_servers
 694 -------------------
 695   Required:
 696         domain=bar.bz
 697         registrar=server.bar.bz
 698         r_port=5060
 699         proxy=proxy.bar.bz
 700         p_port=5060
 701         prov_url=http://server.bar.bz/hermes/prov
 702
 703   Description:
 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.
 708
 709   Return:
 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:
 713                 * Missing parameters
 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.
 719
 720 permission/get
 721 -------------------
 722   Required:
 723         user=foo@bar.bz *
 724
 725   Description:
 726         Gets the permissions value for a user, with no parsing.
 727         The permission system is based on bit-flags, with the following values:
 728                 NOCALLS        1
 729                 EMERGENCY      2
 730                 INTERNAL       4
 731                 VOIP           8
 732                 NATIONAL       16
 733                 SERVICES       32
 734                 INTERNATIONAL  64
 735                 OTHERS         128
 736         The user must match a valid user registration.
 737
 738   Return:
 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.
 742
 743
 744 permission/set
 745 -------------------
 746   Required:
 747         user=foo@bar.bz *
 748         permission=63
 749
 750   Description:
 751         Sets the permissions value for a user directly. The permission
 752         system is based on bit-flags, with the following values:
 753                 NOCALLS        1
 754                 EMERGENCY      2
 755                 INTERNAL       4
 756                 VOIP           8
 757                 NATIONAL       16
 758                 SERVICES       32
 759                 INTERNATIONAL  64
 760                 OTHERS         128
 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.
 767
 768   Return:
 769         Returns 'permission' set to the applied permission value on success.
 770         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 771
 772
 773 BUGS:
 774 ---------------------
 775
 776 api/alias/list destination=foo@bar.bz e164=true
 777         should return an empty array, returns false
 778
 779 TODO list:
 780 ---------------------
 781
 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());
 786
 787 Some TODO's listed above ...
 788
 789 Permissions! (user/permissions?user=...)
 790 The permissions bit-flag seems to be:
 791         NOCALLS        1
 792         EMERGENCY      2
 793         INTERNAL       4
 794         VOIP           8
 795         NATIONAL       16
 796         SERVICES       32
 797         INTERNATIONAL  64
 798         OTHERS         128
 799
 800 can_write() checks!
 801 can_read_full() checks!
 802
 803 Improve robustness of change_pw: fetch old password for rollback/testing.
 804
 805 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
 806
 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.