Authentication and Authorization API Developer's Guide

errorFields Details

The following table lists the information included in the errorFields object in an errorResponse.

Table 1. errorField codes
httpStatus code	HERE errorCode	Description
400	400002	Invalid JSON
400	400003	Content-Type header missing
400	400004	Content-Type header something else than 'application/json'.
400	400200	Received invalid data. `errorFields` provides further information
400	400201	Missing required field. `errorFields.name` describes which field was missing
400	400202	Value cannot be empty. `errorFields.name` describes which field was empty
400	400203	Invalid value. `errorFields.name` describes which field had illegal characters.
400	400217	Not a valid string value. `errorFields.name` describes which field was expecting a string value
400	401300	Invalid client credentials
401	401200	Authorization header missing
401	401202	Malformed OAuth 1.0 header (for example duplicated parameters, missing parameters)
401	401204	Time stamp is outside the valid period
401	401205	Unsupported value for signature method
401	401206	Unsupported value for "oauth_version" parameter (should be 1.0)
401	401207	Nonce already consumed
401	401302	Client does not have access to the endpoint
401	401310	Invalid signature - Attempt to use client ID instead of access key identifier for consumer key
401	400601	Unsupported token format
429	429002	Request blocked because too many requests were made. Wait for a while before making a new request.

Create OAuth1.0 Signature

The first step in creating a signature is to create the signature base string. This string contains the parameters to use when generating the signature.

To begin, make sure you have the information listed in the following table.

Parameter	Description
grant_type	Always use "client_credentials".
oauth_consumer_key	The access key ID for which you want to generate a token. For instructions on creating an access key, see Setting up your team and permissions. In the credentials file that you download when you create an access key, the access key ID is the value in the `here.access.key.id` property.
oauth_nonce	An unique string for this signature. The string cannot have been used in a previous signature. Each request to the Authentication and Authorization API must have a unique signature, and the value in this parameter is what is used to ensure the signature is unique.
oauth_signature_method	Always use "HMAC-SHA256"
oauth_timestamp	The number of seconds since the Unix epoch at the point the request is generated. The Open Location Platform rejects requests created too far in the past or future.
oauth_version	Always use "1.0"

Combine these values into a single string by following these steps:
1. URL encode every key and value.
2. Sort the list of key-value pairs alphabetically by key.
3. Concatenate each key/value pair, separating each with an ampersand character ("&").
The result is a parameter string that looks like this (line breaks are added for legibility):
```
grant_type=client_credentials
  &oauth_consumer_key=access-key-id-1234
  &oauth_nonce=LIIpk4
  &oauth_signature_method=HMAC-SHA256
  &oauth_timestamp=1456945283
  &oauth_version=1.0
```
Combine the HTTP method, base URL, and parameter string into a single string called the "base string". This will be the string from which the signature is generated. The base string is in this format:
```
POST&https://account.api.here.com/oauth2/token&<URL encoded parameter string>
```
The base string consists of:
1. The HTTP method in caps (POST) followed by an ampersand ("&").
2. The URL of the HERE token service followed by an ampersand ("&").
3. The URL-encoded parameter string.
For example (line breaks are added for legibility):
```
POST
  &https%3A%2F%2Faccount.api.here.com%2Foauth2%2Ftoken
  &grant_type=client_credentials%26oauth_consumer_key%3Daccess-key-id-1234%26oauth_nonce%3DLIIpk4%26
oauth_signature_method%3DHMAC-SHA256%26oauth_timestamp%3D1456945283%26oauth_version%3D1.0
```
Note: The URL-encoded base string should contain exactly two ampersands ("&").

Create the Signing Key

The signing key is the URL-encoded access key secret, followed by an ampersand ("&"). You can obtain your access key secret as described in Setting up your team and permissions. Since HERE does not use the "token secret" field, the signing key is just the encoded consumer secret followed by an ampersand ("&"). For example:

NtxCeo4IE3XESAMPLEwY3348TVYPWAcB_-WaoeSAMPLEW-cowuEhn1Xg2cmhP5fqqqq83s0OwpaoNSAMPLE&

Create the Signature

Create the signature by passing the signature base string and signing key to the HMAC-SHA256 hashing algorithm and converting the result to a base64 string.