Generating a Bearer Token

The Location Services API uses the OAuth2 Bearer Token Scheme for authorisation for all CRUD operations (refer to What is REST?).

Request

To generate your token, proceed as follows:

  1. Ensure that you have your apiKey.properties file to hand containing your unique key and secret:

    apiKey.id = <api key id value>
    apiKey.secret = <api key secret value>
  2. Encode the key and secret to Base64 format by entering the following sequence into your favoured BASE64 encoder:

    <api key id value>:<api key secret value>

    Note

    Ensure that the two values are separated by a colon (':') .

    Save the encoded result for use as your particular authorisation string.

  3. Perform a POST request to:

    https://dmo.metapack.com/oauth

    using the authorisation string generated in the previous step:

    Basic <Base64-encoded key and secret>

    of content type:

    application/x-www-form-urlencoded

    and with the following body:

    Key: "grant_type"
    Value: "client_credentials"
    
  4. In summary, ensure that the request is set up as follows in HTTP:

    POST /oauth HTTP/1.1
    Host: dmo.metapack.com
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic <Base64-encoded key and secret>
    "grant_type": "client_credentials"
    

Response

The response from Delivery Options is in JSON format, and will be in the form of an HTTP 200 OK response if the request is successful. For other possible responses, refer to What are the possible Server Responses?.

For example:

HTTP/1.1 200 OK
Access-Control-Allow-Headers: X-Requested-With,Content-Type
Access-Control-Allow-Methods: GET,PUT,POST,DELETE
Access-Control-Allow-Origin: *
Content-Length: 591
Content-Type: application/json; charset=utf-8
Date: Wed, 14 Feb 2020 14:42:51 GMT
X-Powered-By: Express

{
    "access_token": "<Bearer Token>",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "can-update-locations can-create-locations 
    can-manage-opening-times-rules can-search-locations 
    can-delete-own-locations can-retrieve-locations"
}

The fields returned are as follows:

Table 1. Fields returned from Bearer Token API call

Field Name

Description

access_token

The token value to use in calls that require OAuth2.0 authentication (in our case, the calls used to create, modify and delete locations).

expires_in

A TTL (Time to Live) in seconds, i.e. the number of seconds after which the token is no longer valid, e.g. 3600 seconds.

scope

Space-separated list of permissions, from the following:

{
  "permissions": [
    "can-create-locations",
    "can-retrieve-locations",
    "can-update-locations",
    "can-delete-own-locations",
    "can-manage-opening-times-rules",
    "can-search-locations"
  ]
}

token_type

OAuth2.0 token type.


Setup Checklist