From the Trenches: Common authentication issues post Go-Live

A common API error code you might encounter is "PARTNER_AUTHENTICATION_FAILED", which, as you may have guessed, means there's an issue authenticating the application. To determine what exactly is going wrong, you'll need to look at the message that's included in the API response. The three primary values you'll see all start the same, but they each point to different causes. For that reason the second sentence, if present, is the key to determining the cause of failure.

The specified Integrator Key was not found or is disabled. 

The specified Integrator Key was not found or is disabled. An Integrator key was not specified.

 The specified Integrator Key was not found or is disabled. Invalid account specified for user.

(Note: Integrator Key is the old name for integration key)

The specified Integrator Key was not found or is disabled.

As we undergo Legacy Authentication Deprecation, this first error will occur for applications attempting to use Legacy Authentication that have been cut off and are no longer allowed to use the designated insecure methods. If a previously-working integration suddenly starts receiving "The specified Integrator Key was not found or is disabled." with no other error text, reach out to Docusign Support.

Previously, If there was only the first sentence, this error could be taken at face value. That most commonly occurred when attempting to make calls in production while the key only exists in the demo environment or if the key had been deliberately shut off. 

While fully disabling an integration key is fairly rare, it can happen in cases of abuse, if there are service protection concerns, or if authorized by an admin of the account that owns the integration key. If you are certain your key is live in production and your authentication header is built correctly, the recommendation would be to open a Support Case for assistance.

The specified Integrator Key was not found or is disabled. An Integrator key was not specified.

The message "An Integrator key was not specified" typically means Docusign wasn't able to parse your authentication header. If this error occurs while you're using an OAuth Authentication workflow, confirm your header has a key of authorization, and the value has a prefix of Bearer before the token.

The specified Integrator Key was not found or is disabled. Invalid account specified for user.

While you should of course check the obvious—that you are indeed using the correct account ID and the user in question is active on that account—a more common issue is that your application is hitting the wrong server.

Docusign has several server environments, and new ones are added regularly. To confirm the correct environment for a particular account, you need to make a User Info call using that account's credentials. Accounts only change servers in very specific circumstances, so the User Info response can be cached indefinitely. It's generally only necessary to make that call again if a user is added to a new account and the integration needs to be aware of it.

In general, when working with Docusign APIs, Docusign recommends that you set up your application to capture and record the full text of an error response—not just the HTTP status code, or the ErrorCode parameter, but the message as well. Providing the full text of both will go a long way in troubleshooting an issue should the need arise. Capturing the x-Docusign-Tracetoken and providing it to Support will allow the support team to identify the specific failing call in our telemetry.