From the Trenches: Common authentication issues post Go-Live

•

Summary•3 min read

How to troubleshoot common issues with authenticating an application

Additional resources

Additional resources

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)

If there's only one sentence, this error can be taken at face value. This most commonly occurs when attempting to make calls in production while the key only exists in the demo environment.

While disabling an integration key is fairly rare, it can happen in cases of abuse or if there are service protection concerns. If you are certain your key is live in production and your authentication header is built correctly, reach out to Docusign Support if you encounter this error.

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