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.
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
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:
-
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
. -
Go to Headers and enter a value of
application/xml
orapplication/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.
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:
- SNAPLOGIC Documentation
- MULESOFT Documentation
- BOOMI Documentation
- SAP PO Documentation
- WEBMETHODS Documentation
- INFORMATICA Documentation
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.
6. Disable old API Keys
As part of the transition process, please deactivate existing API keys so that they are no longer used after the transition to OAuth2.0.
- Go to Setup > API Keys.
- Edit old API key.
- Click Revoke API Key.
7. Available Resources & Information in the Coupa Success Portal
Coupa Webinars
- March 25, 2022: Transitioning to OAuth(API)
You can also use the following resources to learn more: