What can we help you find? Products Coupa Product Documentation Integration Technical Documentation The Coupa Core API OAuth 2.0 and OIDC OAuth 2.0 Transition Guide

OAuth 2.0 Transition Guide

Introduction

This article discusses the steps you need to complete to configure OAuth Clients in Coupa in order to transition from API keys to OAuth 2.0.

Note

API key sunsetting and transition only affects customer-created API integrations to the Coupa core platform, and does not not affect applications such as Treasury, CSO, Supply Chain Design & Planning, etc.

API keys created by Coupa should not be revoked. These keys will be transitioned separately with no action required from you.

How it works

Note

Please, complete the following steps for all of your Coupa instances (production, test, dev, stage, etc.).

1. Review API keys in Coupa

Log in to your Coupa instance.
Navigate to Setup > API Keys.
Review all keys.

2. OAuth Client creation and scope assignment

Navigate to Setup > Oauth2/OpenID Connect Clients (/oauth2/clients).
Click Create and select Client Credentials in the Grant type dropdown.
Complete the fields and select the scopes (access permissions) the Client needs. Note that if you want to give a Client access to all API endpoints and operations, you will need to add all scopes to that Client.
Once you save the Client, you will get the Client credentials: Identifier, Secret, Oidc Scopes.

3. Credentials test (connectivity test using an HTTP Client like Postman)

Using Terminal (LINK), use the Command line to perform a Curl POST:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=<CLIENT_ID>&grant_type=client_credentials&scope=<SPACE_SEPARATED_LIST_OF_SCOPES>&client_secret=<CLIENT_SECRET>" https://<INSTANCE_DOMAIN>/oauth2/token
Using an HTTP Client like Postman or another REST Client, configure an OAuth2/OIDC Client connection to use the Coupa API.
Select POST.
Set the URL to the instance name where you defined the Client above. For example: https://{your_instance_address}/oauth2/token
Set the headers key value for Content-Type = application/x-www-form-urlencoded
In the POST body set the following values:
1. client_id = <Your Client Identifier value>
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>
Click Send. 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 86,399 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 enter a value of application/xml or application/json in the Accept key field. 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 example you can see a GET API Call to the Invoices API.
Click Send. 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.

4. Build Middleware script/flow for token creation and refresh every 20 hours

Depending on the middleware, configurations may vary. However, it is important to ensure that all integrations using Coupa API keys are updated to use the OAuth token. For the generation and refresh of this token, a new script/flow might need to be created to ensure this is updated every 20 hours. Most of the adapters in the middlewares will refresh the token automatically once the setup is done.

Warning

Changing the scopes in a Client will impact the token generation script/adapter since these are passed in the token generation request.

See below documentation links for different middlewares on how to set up the OAuth2.0 adapter:

5. Update Integrations to use new token generated by script

All existing integrations will need to adopt the OAuth connection and use the token generated by the new script/flow. This can be done in phases, for example, where master data integrations are transitioned first followed by transactional data integrations at a later stage.