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
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:
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.
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.
Signature keyId="hmac-key-1",algorithm="hmac-sha256",headers="(request-target) host date digest content-length",signature="Base64(HMAC-SHA256(signing string))"
Value to pass here is the Tenant ID identifying the tenant to use as context for this request.
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:
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
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.
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:
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
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
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.