Authentication

Authentication is the process which clients can prove their identity and it is required in order to use Situm API. There are two methods to request the authentication to Situm API: Http headers and JWT. Both JWT and API key need to set at least one header in your requests, that also have different purposes due to their own character. In the following chart you can compare the differences between our API keys and JWT in our site. In the following chart you can compare the differences between our API keys and JWT in our site.
API key JWT
You must set at least two headers only for authentication in your requests. Needs to set just one header.
It does not have an expiration date. At Situm API it is valid for 4 days.
It could be used only for reading or both reading and writing data. It is used for both reading and writing data.

API keys

How to generate your API key

You can create an API key very easily through your dashboard.
You can generate your API Key in the Situm Dashboard: Go to your profile section. Click on generate to create your API key.
Account
Your API Key will be displayed immediately.
Account with apikey

How to make a request with your API key

All API requests must be properly authenticated. With your API key, you will be able to build your own apps using the Situm SDKs and consume the Situm REST API. To this extent, you should include the following HTTP headers in all your calls:
  • X-API-EMAIL: the email of the user
  • X-API-KEY: the API key of the user
How to set the authentication header using cURL:
curl -H 'Content-Type: application/json' -H 'X-API-EMAIL: user@example.com' -H 'X-API-KEY: T9NP2lzk+jSI/Oi5DG6ODk57O0pZXdx4'

Types of API keys

There are two types of API keys depending on whether they have read or write permissions. You can change the permissions of your api keys by clicking on Edit link.

Javascript Web Token (JWT)

Create a JWT with user credentials using Basic Auth

Parameters
Authorization required header param
The usermail:password format encrypted in base64
Returns
Returns a Javascript Web Token valid only for 4 days
Error Status Codes
Request url
https://dashboard.situm.es/api/v1/auth/access_tokens
Curl
curl -X POST -H'Authorization: Basic <user:password encoded in base 64>' https://dashboard.situm.es/api/v1/auth/access_tokens
Response body
{
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4MjA4M2U2Zi0yZWEzLTQ1NTEtOWI0NC1lNGI6ZGM1YjY1ODUiLCJlbWFpbCI6InlvdXJ1c2VyQHNpdHVtLmVzIiwib3JnYW5pemF0aW9uX3V1aWQiOiIyNTZhZDhlYS1iNDRmLTRjNGQtOWI4Yi1mZTA4YTAzNTczNmMiLCJpYXQiOjE1Njk5MjI2OTMsImV4cCI6MTU3MDI4MjY5M30.Vcd1KfQ455nVWAYL0T9evecalV7Dk6iXybZQ9t9RGro"
}

Get geofence using JWT

To recover the information of a single geofence, giving its identifier using JWT.
Parameters
Authorization required header param
Bearer token
id required path param
Geofence identifier
organization_id optional query param
Organization identifier
Returns
Returns a geofence object
Error Status Codes
Request url
https://dashboard.situm.es/api/v1/geofences/:id/
Curl
curl  -H 'Content-Type: application/json' -H 'Authorization: Bearer <token_access>' 'https://dashboard.situm.es/api/v1/geofences/8734e5b7-0c46-4c1a-8706-556737d14c2a'
Response body
{
    "id": "8734e5b7-0c46-4c1a-8706-556737d14c2a",
    "created_at": "2019-05-07T11:26:16.840Z[UTC]",
    "updated_at": "2019-05-21T11:45:53.761Z[UTC]",
    "custom_fields": [],
    "code": "222",
    "name": "geofence1",
    "organization_id": "7cc5dc373-94e7-4270-b778-459bf88928f2",
    "description": "<p>222</p>",
    "info": "<p>222</p>",
    "type": "POLYGON",
    "geometric": [
        [
            40.49459442765684,
            -3.592425885144621
        ],
        [
            40.493827484014716,
            -3.5924580716528
        ],
        [
            40.49415384408281,
            -3.5916426801122725
        ],
        [
            40.49459442765684,
            -3.592425885144621
        ]
    ],
    "level_id": 4272,
    "floor_id": 4272,
    "building_id": "2876",
    "deleted": false
}