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 HTTP resources on behalf of that resource's owner. It does this by providing access tokens to third-party clients with the approval of the resource owner. The client then uses the access token to access protected resources.

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: We strongly recommend you 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 setup OAuth access.

To do this:

  1. Contact support@nexmo.com and request OAuth access be enabled for your account. 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