Docs /

Authentication and Authorization Developer Guide

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.

  1. 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"
  2. 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
  3. 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.