EN globe icon
user icon
What can we help you find? Products Platform Integration Playbooks and Resources Integration Knowledge Articles OAuth 2.0 Getting Started with Coupa API

OAuth 2.0 Getting Started with Coupa API

Revised: 18 August 2022

Introduction

This example getting started procedure uses Coupa and Postman to demonstrate how you can set proper key values and scope to unlock the interface for your REST commands.

While this example uses Postman, you can use most any REST client tool to get and refresh an access token that unlocks access to the Coupa API using OAuth 2.0

How it works

Login to Coupa as an integrations enabled administrator to create an OAuth2/OIDC Client with a grant type Client Credentials. Once configured the values of Client ID and Client Secret are used to gain access to the Coupa API.

  1. To set up your Coupa test instance with a new connection, go to Setup > Oauth2/OpenID Connect Clients. You can type ‘oauth’ in the Search box to find it fast.

  2. Click on Create. For Grant Type select: Client credentials. Specify a Name for the Client, Login, Contact info, and Contact Email.

  3. Select the Scopes you would like to include in this API setup. Scopes are like a set of permissions set on the API key.  In order to implement API permissions with OIDC, we've created several new scopes that provide access to specific functionality for the API. Coupa scopes take the form of service.object.right. For example, core.accounting.read or core.accounting.write. You can find the list of scopes and their underlying Coupa permissions by going to the Scope management page at /oauth2/scopes. When you drill down into a scope, you can see the specific API permissions associated with that scope. 
    Scopes are available for review on https://{your_instance_address}/oauth2/scopes.

    To select all the scopes that are available at a time, this document provides the steps.

  4. Click on Save.  Saving the client gives you values of the client Identifier and Secret which are needed to gain access to the API Scopes you have defined for it.  
    Click Show/Hide     to display and copy the Secret

    Note

    Coupa instance addresses take the form of https://{organization_name}.coupahost.com (for customer instances) or https://{organization_name}.coupacloud.com (for partner and demo instances).

    OIDConnect Client Coupa context.png

We need an access token to be able to access APIs and it only lasts for 24 hours, so Coupa’s recommendation is to renew the token every 20 hours (like a refresh token). If the existing token expires, a new token call must be made. This process does not have to be manual as the integration can have the POST call as part of the script to run every 20 hours.

Use Postman or another REST client to configure an OAuth2/OIDC client connection to use the Coupa API.

  1. Select POST.
  2. Set the URI to the instance name where you defined the client above, for example: https://{your_instance_address}/oauth2/token
  3. Set the headers key value for Content-Type = application/x-www-form-urlencoded 

    Using Postman set a header key called Content-Type to: application/x-www-form-urlencoded

  4. In the POST Body set the following values:

    1. client_id = <Your client Identifier value from step 4 above>

    2. grant_type = client_credentials

    3. scope = <Copy/paste all the scopes that you selected in client credentials setup without the comma.>

    4. client_secret = <Copy/paste the Coupa Client Secret value created in Step 4 above>

      Using Postman create a POST body with values like this example.

  5. Click Send and the POST response  has the access_token that was generated to authorize API calls within the defined scope for the next 24 hours (expires_in 86399 seconds). 

    The response to the POST has the response token needed for further use of the API.

  6.  Copy your access_token value from the response body and use it as the Token value in Authorization headers for your Coupa API calls within the scope you defined for this client connection. 

  7. Create a new tab to make API calls to GET, POST, or PUT etc and in the  Authorization part of the request builder define the ‘TYPE’ = OAuth 2.0

  8. Paste the access_token as the Token field value.   

    Use your token in a new API call with an authorization header Token.

  9. Go to Headers and for the Accept key enter a value of: application/xml or application/json.
    You will need to set and define the other request parameters according to the call and the interface you are attempting to use. In the examples pictured you can see a GET API Call to the Invoices API.

    Enter an Accept value like: application/xml or application/json

  10. Click Send and if the request is made properly you should get a response like what is shown below.

    Postman with an invoice returned as an XML response.

With that access_token set in the Authorization header you can make GET, PUT or POST calls to the Client scopes you defined for that Connection.

Additional Resources

Here are some other related topics you might be interested in: