Howto:Authentication in the SOAP API interface
The authentication/user scheme used in the PBX’s SOAP API is sometimes confusing. Here is how it works.
This information applies to
- all PBX platforms
In the PBX’s SOAP API user model, there are 3 levels of authorization.
- the basic access, controlled on the HTTP level
- the “Initialize” level
- the “UserInitialize” level
To execute any SOAP function, you must be authenticated to the PBX. This requires of course a user name and a password. There are three options for this:
- use the gateways admin user name and its password. This will give you full access to the SOAP level.
- use the user name “admin” along with the PBX password. This will give you full access to the SOAP level too.
- use the alias (aka short name) of just any PBX user that has a password defined along with this password. This will give access limited to this user.
Please note that this username and password pair is not sent as an argument to any SOAP function. Instead, it is passed on the underlying HTTP level to the PBX. The exact syntax to do that thus varies greatly depending on the SOAP platform you use. In many platforms, this user/password pair is referred to as “credentials”.
Some of the SOAP functions (such as Initialize and UserInitialize) require a user name as an argument. If so, then use the users cn as the user name. This implies that for calling a SOAP function that requires a user name argument, there must be a corresponding user object in the PBX defined. You can neither use the predefined name “admin” in this context nor the gateway admin account name defined for the gateway.
SOAP functions never have a password within their arguments.
Please note that some SOAP platform do not support HTTP digest authentication. They will be using basic authentication instead. If you implement based on such a platform, you need to enabled basic authentication in the PBX configuration, as it normally is considered unsafe and thus disabled. If you need to enable this thus depends on the SOAP application platform your applications are based on.