API Reference

Integrating Partner Apps with Navigator

This section captures the APIs needed for partner integration and covers specifically the following interfaces:

  • User Data APIs
  • Content Ingestion API
  • Data Logging APIs
  • Data Report Out APIs

API Context

Based on the context of the request, partner integration APIs are bucketed as:

System context API: API run as system, not a user, and requires server trust

User context API: API invoked as a user and requires an authorization

System Context API

These types of APIs run in system context, not run in any specific user context. Since there is no user context involved, there are no user identifiable credentials which could be used to generate the session token. Hence, a separate mechanism is needed to authenticate such requests.

These APIs are generally preset at following path:
/api/pi-api/v1/syscon/

Passphrase Signed Requests

All the APIs in system context will use passphrase signed request. A passphrase used / shared may be different from client secret. This passphrase will be provided to Gooru tenants on specific request. The passphrase won't be shared across tenants or tenant hierarchy - meaning a sub-tenant of a parent tenant needs to use its own passphrase and cannot share passphrase of parent tenant.

Refer to this weblink for detailed explanation and some example.

The following section detail the request signing process and various headers / params involved.

Authorization Header

The HTTP authorization header should be like this:

Signature keyId=,algorithm=,headers=(<space separated list of header names used for request signing>),signature=

All values (not the keys) at the header must be quoted strings.

For example:

Signature keyId="hmac-key-1",algorithm="hmac-sha256",headers="(request-target) host date digest content-length",signature="Base64(HMAC-SHA256(signing string))"

keyId

Value to pass here is the Tenant ID identifying the tenant to use as context for this request.

algorithm

The name of algorithm which was used by client to generate the signature. RSA/DSA (public key signing) is NOT supported currently. Signing with HMAC using passphrase is supported. Following algorithms are supported:

  • hmac-sha1
  • hmac-sha224
  • hmac-sha256
  • hmac-sha384
  • hmac-sha512

headers

The space separated list of HTTP headers which are used for generating the signature. The Authorization header is excluded from server processing. The "date" header is used to determine the skew and is used to avoid replay of requests. By default the skew is set to 30 seconds. Note that there is one specific header named as "(request target)" which when present would denote the value

lowerCasedHttpMethodName uri

The "date" header should be present in format as specified by RFC 1123

EEE, dd MMM yyyy HH:mm:ss zzz

Note that if the digest header is present, and is used in request signing, it will be used to do signature verification. However, system will not validate the request payload itself using the digest.

signature

The base64 encoded signature string.

To generate string which needs to be signed, the HTTP headers should be used in same sequence as they are specified in headers section. Example:

host: localhost:8080

date: Wed, 28 Feb 2018 15:47:19 IST

(request-target): get /api/pi-api/v1/syscon/validateSignedRequest

The format is LOWER-cased header name followed by colon, followed by a space and then value of header. The value of the header should be trimmed. Then there would be a new line to separate it from next header. Once all the specified headers are accumulated in this way, the resulting string should be converted to bytes using UTF-8 and then should be used as byte array to generate the signature.

User Context APIs

These types of APIs run in user context and hence they need to carry an access token identifying the user invoking the action.

These APIs are generally preset at following path

/api/pi-api/v1/usercon/

Access Token At Requests

All the APIs in user context will use access token at request. An access token is generated using user credentials or system context API to get access token.

Note: For a partner using SSO model, the only way to get a user access token is via the SSO login/auth/token calls that are syscon APIs.

In this case, information is sent at HTTP Authorization header

Token accessToken

The access token is validated against token store and if the access token is active (not expired) and is authorized, then the requested operations will be allowed.