There are a handful of element-specific articles available that discuss how to re-authenticate through the API as opposed to through the Cloud Elements user interface, but this article's purpose is to provide guidelines on re-authenticating element instances through an example. Revoking an OAuth token can be useful when testing your application and handling response codes other than 200 when an instance needs to be re-authenticated. As there can be specific requirements between each cloud service endpoint (e.g. Box, Salesforce, Quickbooks) this article will not address how to create a cloud service OAuth application and the discussion relies on OAuth credentials having already been obtained.

The first question that likely crosses your mind when thinking about how to re-authenticate instances is "how can I simulate invalidated/expired/revoked tokens for my instance?" Each software vendor and cloud service endpoint that you interact with can have their own unique ways of allowing your to revoke user tokens through their UI or through API call to `revoke` endpoints, but here are a few examples of calls to revoke OAuth tokens through API:

Box:
curl -X POST \
  https://api.box.com/oauth2/revoke \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=MY_CLIENT_ID&client_secret=MY_CLIENT_SECRET&token=MY_TOKEN'

Salesforce:
curl -X POST \
  'https://na54.salesforce.com/services/oauth2/revoke?token=MY_TOKEN' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Adobe Sign:
curl -X POST \
  'https://secure.na1.echosign.com/oauth/revoke?token=MY_TOKEN' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \

In order to revoke a user's OAuth token you must first determine the existing token value, and one way to do this is to GET /api-v2/instances (with the full Authorization header of your instance user/organization/element tokens) and retrieve the oauth.user.token value from the configuration object. You can get this value through other methods as well, but this API GET call is used in this example. By hitting the above endpoints with the appropriate OAuth Token you can invalidate the authorization for that element instance, then go through the OAuth flow to retrieve a new Provider Code and simply pass the new code to PATCH /api-v2/instances (again with the full Cloud Elements Authorization header for your existing element instance) to re-authenticate it.

To illustrate let's take the element Adobe Sign for example:

1) GET /instances with the full authorization header (User, Organization, and Element tokens)

2) Locate the 'configuration' object, and retrieve the current oauth.user.token value.

3) Make an API call directly against the cloud service endpoint to revoke the OAuth token, and supply the required parameters/payload. Confirm that a successful 200 response is returned indicating that the revocation was successful.

4) Attempt to make any API call against an endpoint of the Element Instance, and confirm that a response is returned such as 401 "Request failed" due to INVALID_ACCESS_TOKEN.

5) Generate an OAuth URL by making a call to GET /api-v2/elements/{elementID}/oauth/url.

6) Enter the resulting OAuth URL into a browser, authenticate with the cloud service, and intercept the oauth provider code that is returned.

7) Make a call to PATCH /api-v2/instances with the full Cloud Elements Authorization header and this providerData.code value.

8) Confirm that the user is successfully re-authenticated, and that API calls can be made successfully against the element instance.