Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

OAuth

You can use the OAuth 1.0a protocol to give your App authorized access to the Nexmo APIs.

OAuth is an open standard that provides client apps with secure delegated access to server resources on behalf of a resource owner. It does it by allowing access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The client then uses the access token to access the protected resources hosted by the resource server.

When you use OAuth for authentication:

  • Nexmo can tell which App and user are calling Nexmo APIs
  • Your app identifies the user
  • The user's privacy is protected

Note: use an existing OAuth Library  for your App.

This section contains:

Setting up OAuth access

OAuth access is associated with a Developer App. You need to create and configure your App before you programm OAuth access into it.

To do this:

  1. Contact support@nexmo.com and request OAuth access. Nexmo support contacts you when access is granted.
  2. Login to Dashboard: https://dashboard.nexmo.com  .
  3. In Dashboard, click Apps > Developer.
  4. Click create a new developer app.
  5. Fill the form and click Save. You see your Consumer Key and Consumer Secret in Dashboard.
  6. Install an OAuth 1.0a library for your programming language from: http://oauth.net/code/  .

Using OAuth in your App

After you have setup OAuth access, include OAuth in your App:

  1. Define the names for incoming return parameters:

    <?php
    // nexmoOAuthDriver.php
    
    define('TOKEN', 'oauth_token');
    define('SECRET', 'oauth_token_secret');
    

  2. Create your OAuth object:

    <?php
    // nexmoOAuthDriver.php
    
    $this->request_string = 'request_token';
    $this->authorize_string = 'authorize';
    $this->access_string = 'access_token';
    
    $this->oauth_baseurl = 'https://dashboard.nexmo.com/oauth/';
    
    /*
    * The consumer key and secret for your App.
    * You find this information in Dashboard.
    */
    $this->consumer_key = '<YOUR Consumer Key>';
    $this->consumer_secret = '<YOUR Consumer Secret>';
    
    //Create a new OAuth object using your Nexmo Consumer Key and Consumer Secret
    $this->oauth = new OAuth( $this->consumer_key  , $this->consumer_secret);
    

  3. Retrieve an OAuth request token:

    <?php
    // nexmoOAuthDriver.php
    try {
      //Retrieve the OAuth token from Nexmo
      $this->token = $this->oauth->getRequestToken( $this->oauth_baseurl . $this->request_string  );
      //Set the local token objects
      $this->request_token = $this->token[TOKEN];
      $this->request_token_secret = $this->token[SECRET];
    } catch (Exception $e){
      echo $e->getMessage();
      return;
    }
    

  4. Authorize OAuth access for this App:

    <?php
    // nexmoOAuthDriver.php
    
    $authorization_url = $this->oauth_baseurl
    . $this->authorize_string
    . '?'
    . http_build_query(array(TOKEN => $this->request_token));
    
    echo "Open the following URL and press Authorize:\n" . $authorization_url  ;
    echo "When you have finished, press any key:\n";
    $enter = trim(fgets(STDIN));
    $this->authorized = true;
    

  5. Retrieve an OAuth permanent access tokens from Nexmo using the request_token and request_token_secret:

    The access token:

    • Gives your App access to Nexmo API.
    • Enables your App to make calls through your Nexmo account.
    <?php
    // nexmoOAuthDriver.php
    
    $this->oauth->setToken($this->request_token, $this->request_token_secret);
    try{
      //Retrieve an access token.
      $token = $this->oauth->getAccessToken($this->oauth_baseurl . $this->access_string);
      $this->access_token = $this->token[TOKEN];
      $this->access_token_secret = $this->token[SECRET];
      $this->access = true;
    } catch (Exception $e){
      echo $e->getMessage();
      return;
    }
    

  6. Set your request parameters:

    <?php
    // nexmoOAuthDriver.php
    
    $this->params = array('from' => 'NexmoOauth' , 'text' => 'hello from Nexmo', 'to' => 'xxxxxxxxxxx' );
    $this->nexmo_requesturl = 'https://rest.nexmo.com/sms/json?';
    

  7. Make a request to the Nexmo APIs:

    <?php
    // nexmoOAuthDriver.php
    
    // Set the OAuth object to the access token retrieved in getAccessToken.
    
    $this->oauth->setToken($this->access_token, $this->access_token_secret);
    try{
    
     $this->oauth->fetch($this->nexmo_requesturl, $this->params, OAUTH_HTTP_METHOD_GET,
                     array('Accept' =>  'application/json'));
     $this->response = $this->oauth->getLastResponseInfo();
    
    } catch(Exception $e) {
     echo $e->getMessage();
         return;
    }
    

The Nexmo OAuth endpoints are:

Type URL
Request Token https://dashboard.nexmo.com/oauth/request_token
Authorize https://dashboard.nexmo.com/oauth/authorize
Authenticate https://dashboard.nexmo.com/oauth/authenticate
Access Token https://dashboard.nexmo.com/oauth/access_token

Running the sample App

The code used in this page is part of a small PHP App that you can run locally. To do this:

  1. Setup OAuth access with Nexmo.
  2. Setup an OAuth 1.0a  library for PHP.
  3. Download the sample from (file: nexmoOAuthDriver.sample text: nexmoOAuthDriver) and rename it nexmoOAuthDriver.php.
  4. In nexmoOAuthDriver.php, replace <YOUR Consumer Key> and <YOUR Consumer Secret> with the values for your App. To find your Consumer Key and Secret, in Dashboard, click Apps > Developer.
  5. Use the following command to run nexmoOAuthDriver. php nexmoOAuthDriver.php