Authentication via Signed String📰

API authentication

If the REST resource you're calling requires API authentication, you must include these HTTP headers with your application's HTTP requests. They are:

• X-Imagen-API-Key: The value must be your application's API key.

• X-Imagen-API-Signature: The value must be a base64 digest of an HMAC-SHA256 hash prepended with the string HMAC-SHA256. The hashed content is a concatenation of a string (see Generating an Imagen API signature) and is signed with your application's secret access key.

• X-Imagen-Date or Date: The value must be the time of the HTTP request in RFC-7231, IMF-fixdate format. This format requires time values in Coordinated Universal Time (UTC), although the format indicates UTC by the three-letter abbreviation for Greenwich Mean Time, "GMT", a predecessor of the UTC name. Required because Imagen will only accept a request if its time stamp is within ±5 minutes of the time (UTC) at which it reaches the service.

• (Optional) Content-Length: Size of the request body, in decimal number of OCTETs, as per RFC-7230.

• (Optional) Content-MD5: base64 of 128-bit MD5 digest of the request body, as per RFC-1864.

• (Optional) Content-Type: Media type of the request body, as per RFC-7231.

Note:X-Imagen-Date is included as some HTTP client libraries do not allow the developer to set the Date HTTP header manually or read its value for inclusion in the X-Imagen-API-Signature. If both X-Imagen-Date and Date are set, Imagen will take the value of X-Imagen-Date and ignore Date. If the 'Date' header (https://tools.ietf.org/html/rfc7231#section-7.1.1.2) is used instead of 'X-Imagen-Date', then Imagen will ignore it unless it uses the RFC-7231, IMF-fixdate format. An example of a time stamp in the correct format is: 'Wed, 03 May 2015 09:04:08 GMT'. Two digits are required for all date and time numbers except for the year, which must be 4 digits. A single space between components is also required. If the format for the 'X-Imagen-Date' header is wrong your request will be rejected with an explanatory error message, so for ease of debugging, we recommend using the 'X-Imagen-Date' header, whether the 'Date' header is also used or not.

Generating an Imagen API signature

The value of X-Imagen-API-Signature is a base64 digest of an HMAC-SHA256 hash. The hashed content is a concatenation of the following string (see StringToSign) and is signed with your application's secret access key.

The values of the standard HTTP headers must be included in the string in the order shown, without header names. If an optional header is not being supplied with the request then the value must be left blank.

StringToSign = HTTPVERB + "\n" +
Content-Length + "\n" +
Content-MD5 + "\n" +
Content-Type + "\n" +
Date + "\n" +
CanonicalizedResource;

StringToSign summary

• \n: All new-line characters shown are required within the signature string, even if the value preceding them is empty.

• HTTPVERB: The HTTP method of your request e.g. POST, GET, PUT. It should always be uppercase.

• Content-Length: The value of your request's Content-Length HTTP header, as per RFC-7230. If not set, leave blank.

• Content-MD5: The value of your request's Content-MD5 HTTP header, as per RFC-1864. If not set, leave blank.

• Content-Type: The value of your request's Content-Type HTTP header (e.g. application/json), as per RFC-7231. If not set, leave blank.

• Date: The value of your request's X-Imagen-Date or Date HTTP header in RFC-7231, IMF-fixdate format.

• CanonicalizedResource: The Imagen REST resource being targeted by the request. For example, the canonicalized resource of https://example.com/core/v1/application is /core/v1/application

Example StringToSign before hashing

GET



Tue, 23 Jun 2015 12:54:48 GMT
/core/v1/application

Note: Content-Length and Content-MD5 values are empty as we have not included these HTTP headers in our request.

Example X-Imagen-API-Signature

Signing our StringToSign with the secret access key ujeQhWRMGY3YfK4vARjUGm9dMZ5lCoxtCMX64vsT and prepending it with HMAC-SHA256 produces the following X-Imagen-API-Signature value:

HMAC-SHA256 4Xk9nftZ1Vr5OlHF4Wrxm5pisgY5WUHsS0bKNjzUJpE=

User authentication

If the REST resource you're calling requires user authentication, you must include two HTTP headers with your application's HTTP requests. They are:

• X-Imagen-API-Key: The value must be your application's API key.

• Authorization: Bearer {userAccessToken}: {userAccessToken} is an Access token granted to your application by a user that has authorized it to perform a specific set of actions on their behalf. An Access token is granted by way of OAuth 2.0.

OAuth in Imagen

If you're developing an Imagen application, it's likely that you'll need to make use of an Imagen REST resource that requires user authentication, which necessitates the usage of an Access token. An Access token represents an Imagen user that has given permission for your application to perform actions on their behalf. To get an Access token for a user, your application must make use of Imagen's OAuth 2.0 implementation.

Imagen OAuth glossary

• Authorization code: If a user authorizes your application to perform actions on their behalf, your application will be passed an Authorization code that must be converted into an Access token within 30 seconds. After 30 seconds has elapsed, the Authorization code will become invalid.

• Access token: Used as part of the Authorization HTTP header when making an HTTP request to an Imagen REST resource that requires user authentication. An Access token never expires, but can be revoked via ImagenWeb.

Supported OAuth grant types

• Authorization code: The most common OAuth 2.0 grant type and most suited to applications where client credentials are stored securely. Authorization code grant type involves the user granting the client an Authorization code that will then be exchanged for an Access token. This must be used with Web applications.

• Implicit: For applications unable to store client credentials securely (such as a mobile or JavaScript application), implicit grant type should be used. This is similar to the Authorization code grant type except that the request returns an Access token instead of an Authorization code. This must be used with Installed applications.

Authorization code URL summary

• imagenweb: URL to your instance of ImagenWeb.

• apiKey: Your application's API Key.

• redirectURI: Your application's redirect URI.

• state: This will be sent back to your application as a query string parameter as part of the HTTP response from ImagenWeb, which can be used to verify that the responder is indeed ImagenWeb.

• scope: A space separated list of scopes that are used to inform the user what your application intends to do on their behalf. The configuration of an application's scope is delegated to an Imagen administrator.

Authorization code grant type

Getting an Access token

To get an Access token for your application, you must first get an Authorization code, which is returned after a user agrees to/authorizes your application. This agreement is made on ImagenWeb and then the resultant Authorization code is returned to your application's Redirect URI as a query string parameter named code.

Getting an Authorization code

To get the aforementioned Authorization code, your application must redirect the user to the following URL:

https://{imagenweb}/oauth/authorize?response_type=code&client_id={apiKey}&redirect_uri={redirectURI}&state={state}&scope={scope}

A successful authorization will pass the application the Authorization code as a query string parameter named code to your application's Redirect URI:

{redirectURI}?code=xyz&state={state}

Converting an Authorization code into an Access token

Once your application has been granted an Authorization code, it has 30 seconds to convert it into an Access token.

To achieve this, it will need to make an HTTP POST request to the following URL:

https://{imagenweb}/oauth/token

With the following POST parameters:

grant_type=authorization_code&code={AuthorizationCode}

In order to authenticate your application with the OAuth 2.0 server, this HTTP request must also include a Basic authentication HTTP header, where the username is your application's API Key and password is the Secret access key.

In summary, the equivalent cURL command for this HTTP POST request should look like:

curl -u {APIKey}:{SecretAccessKey} https://{imagenweb}/oauth/token -d 'grant_type=authorization_code&code={AuthorizationCode}'

A successful Access token request will return a standard Access token in JSON format:

{"access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35","token_type":"bearer","scope":null}

At this point, your application has an Access token.

Implicit grant type

Getting an Access token

To get an Access token, your application must redirect the user to the following URL:

https://{imagenweb}/oauth/authorize?response_type=token&client_id={apiKey}&redirect_uri={redirectURI}&state={state}&scope={scope}

If the redirect_uri is a URL, an Access token will be returned in the JSON format:

{"access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35","token_type":"bearer","scope":null}

Other supported Redirect URIs

• urn:ietf:wg:oauth:2.0:oob: The Access token will be returned in the title bar of the browser and the web page will prompt the user to copy and paste the code into their application. This is useful when the application is unable to listen on an HTTP port.

• urn:ietf:wg:oauth:2.0:oob:auto: The Access token will be returned in the title bar of the browser and the web page will instruct the user to close the window. This is useful when your application reads the Access token from the title of the HTML page, but is unable to close the page itself.

Note: It is recommended that you make use of the Download JSON option for your application, which can be found on the Your applications page on ImagenWeb. The JSON file contains your application's API Key, Secret access key, Redirect URI and scopes.

Note: An Access token never expires, but can be revoked via ImagenWeb. If it is revoked, a new Access token must be regenerated.