{"_id":"5d9a1ccf28154700114a75c7","project":"56439dfe9eebf70d00490d54","version":{"_id":"5864d2df79ce642d00f0fec7","project":"56439dfe9eebf70d00490d54","__v":18,"createdAt":"2016-12-29T09:09:51.074Z","releaseDate":"2016-12-29T09:09:51.074Z","categories":["5864d2df79ce642d00f0fec8","5864d2df79ce642d00f0fec9","5864d2df79ce642d00f0feca","5864d2df79ce642d00f0fecb","5864d2df79ce642d00f0fecc","5864d2df79ce642d00f0fecd","5864d2df79ce642d00f0fece","5864d2df79ce642d00f0fecf","5864d2df79ce642d00f0fed0","5864d2df79ce642d00f0fed1","5864d2df79ce642d00f0fed2","5864d2df79ce642d00f0fed3","5864d2df79ce642d00f0fed4","5864d2df79ce642d00f0fed5","5864d2df79ce642d00f0fed6","5864d2df79ce642d00f0fed7","5864d2df79ce642d00f0fed8","5864d2df79ce642d00f0fed9","5864d2df79ce642d00f0feda","5864d2df79ce642d00f0fedb","5864d2df79ce642d00f0fedc","5864d2df79ce642d00f0fedd","5864d2df79ce642d00f0fede","598aa64f4b6e990019b7a2d2","599bc76bc03fa2000f83db2a","599bcc3c3c5bf7000f3434fc","5d427dc9fa56fa0011135058","5d429c616863d5003af785a7","5d429e0889418f00c5e95d3f","5d42b5f098b05e003acb08b4","5d43c16985775c00ebeede3b","5d43d15446d584003da91e6d","5d43d61a5bdac50011b6f234","5d43d7c2db365100640dbc58","5d43d954bffa8400ff7efa78","5d43e414cf4f03005944344c","5d43eb42db365100640dbe4a","5d43ee6c78121b0057bc1dbf","5d9a18b4afc33400126c4e6f","5dc4f96dbb5da3006c8f5660"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"category":{"_id":"5d9a18b4afc33400126c4e6f","project":"56439dfe9eebf70d00490d54","version":"5864d2df79ce642d00f0fec7","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-10-06T16:39:16.979Z","from_sync":false,"order":38,"slug":"partner-integration","title":"Partner Integration"},"user":"56d5424ba4a9211b00c8f20a","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-10-06T16:56:47.038Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"This section captures the APIs needed for partner integration and covers specifically the following interfaces: \n\n* User Data APIs\n* Content Ingestion API\n* Data Logging APIs\n* Data Report Out APIs\n\n\n#API Context\nBased on the context of the request, partner integration APIs are bucketed as:\n\nSystem context API: API run as system, not a user, and requires server trust\n\nUser context API: API invoked as a user and requires an authorization\n\n##System Context API\nThese 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.\n\nThese APIs are generally preset at following path:\n/api/pi-api/v1/syscon/\n\n###Passphrase Signed Requests\nAll 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.\n\nRefer to this [weblink](https://tools.ietf.org/html/draft-cavage-http-signatures-03#page-6) for detailed explanation and some example.\n\nThe following section detail the request signing process and various headers / params involved.\n\n**Authorization Header**\n\nThe HTTP authorization header should be like this:\n\n`Signature keyId=,algorithm=,headers=(<space separated list of header names used for request signing>),signature=`\n\nAll values (not the keys) at the header must be quoted strings.\n\nFor example:\n\n`Signature keyId=\"hmac-key-1\",algorithm=\"hmac-sha256\",headers=\"(request-target) host date digest content-length\",signature=\"Base64(HMAC-SHA256(signing string))\"`\n\n\n**keyId**\n\nValue to pass here is the Tenant ID identifying the tenant to use as context for this request.\n\n**algorithm**\n\nThe 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:\n\n* hmac-sha1\n* hmac-sha224\n* hmac-sha256\n* hmac-sha384\n* hmac-sha512\n\n**headers**\n\nThe 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\n\n`lowerCasedHttpMethodName uri`\n\nThe \"date\" header should be present in format as specified by RFC 1123\n\n`EEE, dd MMM yyyy HH:mm:ss zzz`\n\nNote 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.\n\n**signature**\n\nThe base64 encoded signature string.\n\nTo generate string which needs to be signed, the HTTP headers should be used in same sequence as they are specified in headers section. Example:\n\n`host: localhost:8080`\n\n`date: Wed, 28 Feb 2018 15:47:19 IST`\n\n`(request-target): get /api/pi-api/v1/syscon/validateSignedRequest`\n\nThe 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.\n\n##User Context APIs\nThese types of APIs run in user context and hence they need to carry an access token identifying the user invoking the action.\n\nThese APIs are generally preset at following path\n\n`/api/pi-api/v1/usercon/`\n\n###Access Token At Requests\nAll 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. \n\n*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.*\n\nIn this case, information is sent at HTTP Authorization header\n\n`Token accessToken`\n\nThe 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.","excerpt":"","slug":"integrating-partner-apps-with-navigator","type":"basic","title":"Integrating Partner Apps with Navigator"}

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](https://tools.ietf.org/html/draft-cavage-http-signatures-03#page-6) 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.