Requests will require the client to be authenticated. Clients must provide one of the following:
If both an Api key and an authentication token are provided with a request, the Api key will be used for authentication.
Authentication tokens are obtained from the Identity service and expire after 24 hours. Once the token is obtained, the client must put it in the HTTP 'Authorization' request header using the 'Bearer' authentication scheme:
Authorization: Bearer {token}.
API keys are used at login to identify an application to the platform and have permission to a subset of platform functionality. To use an API key, the client must either add it as a url parameter in HTTP requests (less secure), or use the key to sign the request (more secure).
The key as a url parameter in HTTP requests:
?key={api key}
A signature added the Authorization header using the 'NNAKeySig' authentication scheme. In addition, a timestamp must be provided:
nna-date: {timestamp}
Authorization: NNAKeySig {api key id}:{signature}
Requests must include a timestamp with the request. You must specify the timestamp in the nna-date header, and the timestamp must conform to the IETF RFC 1123 specification. For example:
nna-date: Tue, 29 Mar 2015 21:21:21 GMT
The Signature string should be in the following format: {timestamp}\n{absolute path}, where the timestamp matches the nna-date header timestamp. Query string is ommitted. For example, the Signature string to retrieve all web applications would be:
Tue, 29 Mar 2015 21:21:21 GMT\n/api/v1/applications/web
The Signature string to retrieve a web application would be something like:
Tue, 29 Mar 2015 21:21:21 GMT\n/api/v1/applications/web/app123
To encode the Signature string, call the HMAC-SHA256 algorithm, using the Api key as the key on the Signature string, and encode the result as Base64. Next, construct the Authorization header using the Api key id and encoded signature, and add the header to the request. For example:
Authorization: NNAKeySig C29B3F01-8BE2-4DB4-9C42-0E6DD386D72D:NTa2cFzQkef5sZu91ELUb0aXp1eQE=