[% IF uri -%] [% END -%] [% title %] [% IF uri -%] [% END -%] Authentication and authorization on the Sipwise NGCP HTTP API is performed via HTTP Basic Auth or SSL Client Certificates. HTTP Basic Auth You can authenticate against the API using your normal NGCP Panel administrator or reseller login credentials with the realm api_admin_http. Examples
Using cURL on the Shell

With cURL, use --user username:password option to specify your access credentials. Specifying the realm is not needed here. curl -i -X GET --user myuser:mypassword https://example.org:1443/api/ Additionally use the --insecure option if you are testing against a self-signed server certificate.

Using Perl LWP::UserAgent

With LWP::UserAgent, set the credentials using the credentials() function. The first parameter is your server (credentials are only sent if the host:port in the request matches the one specified here), the second one is the realm (always api_admin_http), the third one is your username, and the fourth is the password. #!/usr/bin/perl -w use strict; use LWP::UserAgent; my $ua = LWP::UserAgent->new(); # set to 0 if using a self-signed certificate $ua->ssl_opts(verify_hostname => 1); $ua->credentials('example.org:1443', 'api_admin_http', 'myuser', 'mypassword'); my $res = $ua->get('https://example.org:1443/api/'); if($res->is_success) { print $res->as_string; } else { print STDERR $res->status_line, "\n"; }

Using PHP cURL

Same as with Perl's LWP::UserAgent described above, you have to set the credentials using curl_setopt_array() with the parameter CURLOPT_USERPWD specifying your username and password. $ua = curl_init(); $options = array( CURLOPT_USERPWD => "myuser:mypassword", CURLOPT_RETURNTRANSFER => true, // set to false if using a self-signed certificate CURLOPT_SSL_VERIFYHOST => false, CURLOPT_SSL_VERIFYPEER => false, ); curl_setopt_array($ua , $options); curl_setopt($ua, CURLOPT_URL, 'https://example.org:1443/api/'); $res = curl_exec($ua); if(!$res) { echo "Curl Error : " . curl_error($ua); } else { echo $res; }

SSL Client Certificates You can generate and download client certificates for administrators and resellers via the NGCP Panel in the Administrators view. In order to do so, your server certificate MUST support SSL client CA and SSL client CA. You can verify it with the following command: openssl x509 -purpose -noout -in /path/to/ca-cert.pem For the actual client authentication, you will need two files which you can download from the panel after creating the client certificates:
  1. The client certificate generated via the NGCP Panel. This is usually labelled NGCP-API-client-certificate-xxxxx.pem.
  2. The CA certificate used to sign the server certificate, in case it as been self-signed or the CA is not recognized by the client host environment.
Examples
Using cURL on the Shell

With cURL, use --cert /path/to/NGCP-API-client-certificate-xxxxx.pem to specify the client certificate, and --cacert /path/to/ca-cert.pem to specify the CA certificate in case of a self-signed server certificate. curl -i -X GET --cert /path/to/NGCP-API-client-certificate-xxxxx.pem --cacert /path/to/ca-cert.pem https://example.org:1443/api/ Additionally use the --insecure option if you are testing against a self-signed server certificate.

Using Perl LWP::UserAgent

With LWP::UserAgent, set up the SSL client certificates using the ssl_opts() function. Since the key file downloaded from the NGCP Panel combines both the client key and the certificate into one single file, use the same filename for the SSL_cert_file and SSL_key_file option. #!/usr/bin/perl -w use strict; use LWP::UserAgent; my $ua = LWP::UserAgent->new(); $ua->ssl_opts( SSL_cert_file => '/path/to/NGCP-API-client-certificate-xxxxx.pem', SSL_key_file => '/path/to/NGCP-API-client-certificate-xxxxx.pem', SSL_ca_file => '/path/to/ca-cert.pem', # set to 0 if using a self-signed certificate verify_hostname => 1, ); my $res = $ua->get('https://example.org:1443/api/'); if($res->is_success) { print $res->as_string; } else { print STDERR $res->status_line, "\n"; }

Using PHP cURL

Same as with Perl's LWP::UserAgent described above, you have to set the key and certificate paths using curl_setopt_array(), with the parameters CURLOPT_SSLCERT and CURLOPT_SSLKEY pointing to your client certificate. $ua = curl_init(); $options = array( CURLOPT_SSLCERT => '/path/to/NGCP-API-client-certificate-xxxxx.pem', CURLOPT_SSLKEY => '/path/to/NGCP-API-client-certificate-xxxxx.pem', CURLOPT_CAINFO => '/path/to/ca-cert.pem', CURLOPT_RETURNTRANSFER => true, // set to false if using a self-signed certificate CURLOPT_SSL_VERIFYPEER => true, CURLOPT_SSL_VERIFYHOST => true, ); curl_setopt_array($ua , $options); curl_setopt($ua, CURLOPT_URL, 'https://example.org:1443/api/'); $res = curl_exec($ua); if(!$res) { echo "Curl Error : " . curl_error($ua); } else { echo $res; }

[% # vim: set tabstop=4 syntax=html expandtab: -%]