OAuth 2.0 Getting Started with Coupa API
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.
-
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.
-
Click on Create. For Grant Type select: Client credentials. Specify a Name for the Client, Login, Contact info, and Contact Email.
-
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
orcore.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 onhttps://{your_instance_address}/oauth2/scopes
.
To select all the scopes that are available at a time, this document provides the steps. -
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 SecretNoteCoupa instance addresses take the form of
https://{organization_name}.coupahost.com
(for customer instances) orhttps://{organization_name}.coupacloud.com
(for partner and demo instances).
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.
https://{your_instance_address}/oauth2/token
application/x-www-form-urlencoded
In the POST Body set the following values:
client_id = <Your client Identifier value from step 4 above>
grant_type =
client_credentials
scope = <Copy/paste all the scopes that you selected in client credentials setup without the comma.>
client_secret = <Copy/paste the Coupa Client Secret value created in Step 4 above>
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).
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.
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
Paste the access_token as the Token field value.
Go to Headers and for the Accept key enter a value of:
application/xml
orapplication/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.
Click Send and if the request is made properly you should get a response like what is shown below.
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: