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 this 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. On the top-right of Dashboard, click the arrow next to <username>, then click Oauth apps.
  4. Click Add a new 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:
    nexmoOAuthDriver.php
    define('TOKEN', 'oauth_token');
    define('SECRET', 'oauth_token_secret');
    
  2. Create your OAuth object:

    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:

    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:

    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.
      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:
    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:

    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;
            }
    

Note: The Nexmo OAuth endpoints are:

  • 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 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
Previous   Next