Authentication

When interacting with RealTheory APIs, each call must be authenticated and authorized.

To authenticate with a RealTheory API, you must include an authorization header with a custom payload that includes a HMAC signature. This custom payload is submitted using the Basic HTTP access authentication protocol across HTTPS.

The structure of the authorization header is as follows:

Authorization: Basic <payload>

where the payload is the Base64 encoding of the following structure

{domain}\{username}:{secret}\{HMAC}

where:

• {domain} is your RealTheory account name.
• {username} is your RealTheory username.
• {secret} is a RealTheory security token or your API Key.
• {HMAC} is a cryptographic signature used to verify the integrity and authenticity of any request.

For the example below, consider the following hypothetical security credentials for your RealTheory account:

• Domain: acme
• Username: APIKey1
• Secret: 41698726-5B09-4F24-BDE2-FF0A91CA426F
• HMAC: RTv1-SHA256-bAcoIce1w06fxl34V6WNpcoBKDzqd4VXvy6FXpnfFgY=

Prior to Base64 encoding, an example payload for the acme domain might look like:

acme\APIKey1:41698726-5B09-4F24-BDE2-FF0A91CA426F\RTv1-SHA256-bAcoIce1w06fxl34V6WNpcoBKDzqd4VXvy6FXpnfFgY=

After Base64 encoding the authorization header value, the full header, with key, might look like:

"Authorization": "Basic YWNtZVxBUElLZXkxOjQxNjk4NzI2LTVCMDktNEYyNC1CREUyLUZGMEE5MUNBNDI2RlxSVHYxLVNIQTI1Ni1iQWNvSWNlMXcwNmZ4bDM0VjZXTnBjb0JLRHpxZDRWWHZ5NkZYcG5mRmdZPQ=="

How To Calculate the HMAC

To create the HMAC, you first concatenate selected elements of the request to form a string. You then use your API KEY to calculate the HMAC of that string.

Following is pseudo grammar that illustrates the construction of the HMAC:

HMAC = RTv1-SHA256-Signature

Signature = Base64( HMAC-SHA256( UTF-8-Encoding-of( YourAPIKey ), UTF-8-Encoding-Of ( StringToSign ) ) );

StringToSign = HTTP-Verb + "\n" +
	Content-MD5 + "\n" +
	Content-Type + "\n" +
	TimeStamp + "\n" +
	CanonicalizedResource;

Considerations

The first few header elements of StringToSign (Content-MD5, Content-Type and TimeStamp) are positional in nature. StringToSign does not include the names of these headers, only their values from the request. If a positional header called for in the definition of StringToSign is not present in your request (for example, Content-MD5 or Content-Type are meaningless and not present for GET requests), substitute the empty string ("") for that position.

The TimeStamp must be in Coordinated Universal Time (UTC) and must be formatted according to the ISO 8601 specification. For example, the time would be represented as 20201128T152924Z for November 28, 2020, at 15:29:24 UTC.

How to Determine the Canonicalized Resource

The canonical resource refers to the URL path encoded version of the absolute path portion of a request URI, starting with the "/" that follows the domain name and up to the end of the string or to the question mark character ('?') if you have query string parameters. If the absolute path is empty, use a forward slash character (/).

Consider the following examples:

Example 1:
Consider the following request URI:

https://myendpoint.realtheory.io/theory/api/v1/k8ssummary/clustersummaries?index=0&count=100&order=metadata.name&direction=0

The resulting canonicalized resource would be

/theory/api/v1/k8ssummary/clustersummaries

Example 2:
Consider the following request URI:

https://myendpoint.realtheory.io/theory/api/v1/k8scost/namespacecosts/{53214960-fda3-4089-9e12-a7f476317352}/daily/usd?offset=7d&span=7d

The resulting canonicalized resource would be

/theory/api/v1/k8scost/namespacecosts/%7B53214960-fda3-4089-9e12-a7f476317352%7D/daily/usd

Note: { and } characters are encoded to %7B and %7D in the example above.

For a full, step-by-step walkthrough of how to create a RealTheory authorization header, click Authentication Walkthrough