• Last edited on: 19 August 2022

OAuth 2.0 Transition Guide


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

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

2. OAuth Client creation and scope assignment

  1. Navigate to Setup > Oauth2/OpenID Connect Clients (/oauth2/clients).
  2. Click Create and select Client Credentials in the Grant type dropdown.
  3. 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. 
    Create Client screen.
  4. Once you save the Client, you will get the Client credentials: IdentifierSecretOidc Scopes.
    Oath client information returned after saving.

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

  1. 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
    Curl POST example.
  2. Using an HTTP Client like Postman or another REST Client, configure an OAuth2/OIDC Client connection to use the Coupa API.
  3. Select POST.
  4. Set the URL to the instance name where you defined the Client above. For example: https://{your_instance_address}/oauth2/token
  5. Set the headers key value for Content-Type = application/x-www-form-urlencoded
    Content-Type POST example.
  6. 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>
      POST body settings.
  7. 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). 
    POST response example.

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

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

  10. Paste the access_token as the Token field value.
    Token field value example.

  11. 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.
    Accept key field example.

  12. 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.
    Successful request example.

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.

Flow example.

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.

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.

  1. Go to Setup > API Keys.
  2. Edit old API key.
  3. Click Revoke API Key.

7. Available Resources & Information in the Coupa Success Portal

Coupa Webinars

You can also use the following resources to learn more:

Related Items

Querying Options

21 October 2016

See how you can use queries to quickly identify and pull the data you require.

Special Actions and API Notes

21 October 2016

Additional info on how to use the Coupa API.

Differences between XML and JSON in Coupa

16 December 2016


24 April 2017

Learn about the types of arguments that Coupa supports in conjunction with operators.