FYI: new authentication error message in the GraphQL API

Summary

On Monday the 9th of October the GraphQL API will start returning a new error message in cases where the Authorization header is non-empty, but its value is not valid as any of the forms of credential that the API accepts.

Details

Currently, the API treats requests with invalid credentials in the Authorization header as equivalent to successful authentication as a user with no permissions, so that if the request attempts to access a restricted part of the schema, the response includes a KT-CT-1111: Unauthorized. error, like so:

{
  "errors": [
    {
      "message": "Unauthorized.",
      ...
      "extensions": {
        "errorType": "AUTHORIZATION",
        "errorCode": "KT-CT-1111",
        "errorDescription": "The viewer is not authorized to execute the query/mutation. Check authentication or roles/permissions."
      }
    }
  ],
  ...
}

Once this change goes live, the error raised in this situation will have the code KT-CT-1143:

{
  "errors": [
    {
      "message": "Value of 'Authorization' header is not a valid credential.",
      ...,
      "extensions": {
        "errorType": "AUTHORIZATION",
        "errorCode": "KT-CT-1143",
        "errorDescription": "The value of the HTTP Authorization header is not recognized as a valid access credential for this API. Valid credentials can be generated by calling the obtainKrakenToken mutation."
      }
    }
  ],
  ...
}

We hope that this will make the error output of the API more useful, inasmuch as the new error will draw a distinction between authentication errors (where the solution is to get a new token) vs. authorization errors (where authentication has succeeded, but the viewer needs different access privileges than they currently have). In most cases, the visible result of this change will simply be that one error condition is replaced by another, but there is one case where the behaviour of the API is changing in a more significant way:

Access to public API resources

In the case where the request selects members of the GraphQL schema that are accessible to the public (such as the obtainKrakenToken mutation), once this change is made the error will still be raised if parsing of a non-empty Authorization header fails, even though authentication is not required for these schema members. This is similar to the existing behaviour of the API when called with an expired Kraken Token. To avoid this error, we recommend ensuring that the Authorization header is empty for any API call that requests strictly public resources.