Authorization Header

In order to access any features of the MyPreferences WebAPI services, an authorization field must be included in the HTTP Header request regardless of the nature of the request. The authorization field must also include the proper PossibleNow authorization scheme, as well as the proper authorization parameters, which are driven by the type of Scheme selected. As per the RFC 7235, the Authorization header must conform to the following format with the scheme and parameters being separated by a space.

AUTHORIZATION: <scheme> <parameters>

PossibleNow Authorization Schemes

Currently there are only two scheme types and one available scheme identifier for authorization. Future schemes may be added to address any weaknesses in the Authorization header by adding or removing additional parameters. The authorization scheme types allow for a keyed hash and un-keyed hash. It is highly recommended that the keyed hash scheme be used whenever possible as it is more secure. Please note that the authorization scheme is case insensitive.

  • Un-keyed Hash Scheme: SchemeIdentifier-CryptoHashIdentifier
  • Keyed Hash Scheme: SchemeIdentifier-HMAC-CryptoHashIdentifier

An example of each of the two scheme types:

  • Un-keyed Hash Scheme: PNAUTHINFO3-SHA256
  • Keyed Hash Scheme: PNAUTHINFO3-HMAC-SHA256

The SchemeIdentifier drives and defines the authorization process and parameters. Each available scheme identifier will be addressed in the following sections.

The CryptoHashIdentifier is the name of the hash algorithm that is used to generate the signature parameter in all of the scheme authorization parameters. The following hash algorithms are currently available:

  • SHA256
  • SHA384
  • SHA512

Available Schemes

Request Failures

401 Authorization errors

When a request is rejected due to an authorization failure, the HTTP Status Code 401 Unauthorized is returned, as well as a more detailed error in the body. An example of failed request is shown below. 

HTTP/1.1 401 Unauthorized
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
WWW-Authenticate: PNAUTHINFO3 realm="https://pm.mypreferences.com"
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcZGV2XE15UHJlZmVyZW5jZXNcU291cmNlXFdlYlxNeVByZWZlcmVuY2VzLlJFU1RcTXlQcmVmZXJlbmNlcy5SRVNUXGFwaVwzXFBOTzRXXFByb2dyYW1z?=
X-Powered-By: ASP.NET
Date: Fri, 14 Aug 2015 21:22:27 GMT
Content-Length: 68
{"Message":"Invalid Authorization Header: The scheme is invalid.  The scheme should contain either PNAUTHINFO3-<cryptoalgorithmname> or PNAUTHINFO3-HMAC-<cryptoalgorithmname>.  For example: PNAUTHINFO3-HMAC-SHA265."}

The scheme is invalid

Thiis error occurs when authorization scheme is invalid. For example, if the scheme PNAUTHINFO100-SHA256 was sent then the request would be rejected as there is no PNAUTHINFO100 scheme.

The specified date does not match an expected ISO 8601 format

This error occurs when the Issued Timestamp is either not in the expected ISO 8601 encoded format or the date is set in the future. requests with future dates will be rejected.

The difference between the issued timestamp and the current time is too large

This error occurs when the authorization request has expired. For example, if the expiration window is 60 seconds and the current time is 2015-08-13T12:35:00 and the Issued Timestamp is 2015-08-13T07:00:00, then the authorization request has expired and will be rejected.

Missing Authorization Header

This error occurs when a request is sent without an authorization header field.

Unable to authenticate request

This is a generic authorization failure that can be caused by any of the following conditions:

  • The authorization field header is incomplete, missing parameters.
  • The authorization field header is incomplete, missing fields within the credential parameter.
  • The generated signature does not match the fields defined by the authorization scheme.
  • The UserId does not match any known users for the supplied ClientId.

404 Resource Not Found

In addition to the standard 404 status caused by accessing an invalid URL or resource, this status code will also be returned when a client id is invalid. When an invalid client id is supplied in the URL, one that does not exist within the MyPreferences system, a 404 will be returned instead of a 401. Please note that this failed request will not supply a message in the body. 

HTTP/1.1 404 Not Found
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcZGV2XE15UHJlZmVyZW5jZXNcU291cmNlXFdlYlxNeVByZWZlcmVuY2VzLlJFU1RcTXlQcmVmZXJlbmNlcy5SRVNUXGFwaVwzXEFDb21wYW55XFByb2dyYW1z?=
X-Powered-By: ASP.NET
Date: Mon, 17 Aug 2015 17:05:39 GMT
Content-Length: 0