Improvements to authentication errors for V3 endpoints in developer preview program

[zwolfson]

What’s happening

We are adding new information about errors returned about authentication.  These new errors will allow you to troubleshoot easier when things go wrong.  This change puts authentication errors in the same shape as other errors. 

This change only affects APIs currently in the developer preview program. We do not expect this to break existing integrations. 

Previously a missing authentication method error will look like:

{

    "status": "error",

    "message": "Csrf token is missing from the request.",

    "correlationId": "c1010b3d-3453-4fe8-a0cd-afbda4f58a38",

    "engagement": {

        "hapikey": "hapikey not engaged. hapikey is not present in query params.",

        "oauth-token": "oauth-token not engaged. OAuth access token not found in request header.",

        "shhkey-v1": "shhkey-v1 not engaged. Shhkey not found in the request header.",

        "app-cookie": "Engaged",

        "internal-cookie": "internal-cookie not engaged. Cookie not found in the request."

    },

    "requestId": "5822d58c-9384-4636-a61d-6cc017247794"

}

After this change they will look like:

{

    "message": "Authentication credentials not found. This endpoint supports both API Key and OAuth 2.0 authentication. You can find more details at https://developers.hubspot.com/docs/methods/auth/oauth-overview and https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key."

    "correlationId": "5b5f2f38-fb61-4be7-b228-3bd61b06f7f5",

    "category": "INVALID_AUTHENTICATION",

    "links": { 

        "api key": "https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key",

        "oauth": "https://developers.hubspot.com/docs/methods/auth/oauth-overview"

     }

}

This introduces the category and links keys at the top level to be consistent with other errors generated by HubSpot. 

When is this happening?

This change will go live tomorrow on March 12th, 2020

If you have any questions, join the conversation here.