Token Request

To obtain a Soracom Endorse token, simply make an HTTP GET or POST request to the Endorse endpoint: https://endorse.soracom.io:

curl https://endorse.soracom.io
>{"token":"eyJraWQiOiJ2MS1hYmNkZWYwMDAwMDAwMDAwMDAwMDAwMDAxMjM0NTY3OC14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTExMTYzMDEsImp0aSI6ImhrSzdxTnlYekVNVkFYZlRxMU1CdUEiLCJpYXQiOjE0NTExMTYxMjEsIm5iZiI6MTQ1MTExNjA2MSwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiIyOTUwMDAwMTIzNDU2NzgiLCJpbWVpIjoiODAwMDAwMDEyMzQ1Njc4In19.abcdef******************12345678"}

The token will be returned as a JSON object, which contains a token key.

Request Parameters

When Endorse issues a token, the token is signed by Endorse using a secret key. You can obtain the public key signature used by Endorse during token signing to verify that the token has not been tampered.

In some cases, you may want to add additional data to the token before the token is signed by Endorse, in order to use the same verification mechanism for custom data. Doing this allows you to embed extra data, such as a username or session ID, while similarly verifying that the custom data has not been tampered.

In order to add custom data to the token, simply add a query string to the original HTTP GET token request:

curl https://endorse.soracom.io?username=sora&sessionId=123

Or as the request body of an HTTP POST request:

curl -X POST \
>  -b '{
>    "username": "sora",
>    "sessionId": "123"
>  }' \
>  https://endorse.soracom.io

Each parameter will be appended to the token as part of a requestParameters property in the token claims. For example, when inspecting the payload of the token issued from the above request, the payload will look similar to this:

{
  // additional token data
  "soracom-endorse-claim": {
    "imsi": "295000012345678",
    "imei": "800000012345678",
    "requestParameters": {
      "username": "sora",
      "sessionId": "123"
    }
  }
}