Getting Started / Authentication

Authentication

To get started using the API you'll need to authenticate with it using the login resource.

There are two ways to authenticate with the API, either using the central auth.pegasusgateway.com server or your Pegasus domain URL.

When using the central authentication server (https://auth.pegasusgateway.com) the parameters to pass are your username (email address), password, and the gateway host name.

When using your Pegasus domain URL the API url changes to: https://www.yourpegasusdomain.com/api/login and the parameters to pass are only the username and password.

Authentication examples

Central Auth

curl --request POST \
     --url https://auth.pegasusgateway.com/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "username": "[email protected]",
     "password": "*********",
     "gateway": "cloud.pegasusgateway.com"
}
'

Pegasus domain URL

curl --request POST \
     --url https://www.yourpegasusdomain.com/api/login \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "username": "[email protected]",
     "password": "*********"
}
'

The response from the login method generates a valid authentication API token (auth) referred to as a session token. This session authentication token must be used in subsequent API requests in order to keep using the resources.

{
  "message": "User successfully authenticated",
  "app": null,
  "auth": "208b1016f390852181c88cc85f744e3ab9b0d311ba880b3996bfa0ce"
}

The token can be passed in one of two ways:

Note that by default tokens expire after 60 minutes of no requests made with the token, unless you set the scheme to infinite or change its duration.

📘

Content Type Header

When sending JSON make sure you use the appropriate content-type header: Content-Type: application/json

Get User's Info

If you have a session token you can use the Get user info method in order to obtain the user's information.

$ curl --request GET \
     --url 'https://api.pegasusgateway.com/user?auth=AUTH_SESSION_TOKEN' \
     --header 'Accept: application/json'

{
  "username": "[email protected]",
  "scopes": {
    "sims": "r",
    ...

Click here if you're looking for information on how to allow an application to be embedded in Pegasus.

Application Tokens

We saw above an example of generating an authentication token which grants the user access to all the permissions/scopes and groups, etc for the user that authenticated.

There are 2 more types of tokens the API uses:

• Application
• Receiver

Application tokens are used to limit the access to the API based on criteria/permissions you choose, they represent a virtualized version of the user that created them because they can inherit their permissions (note that you can't create an application token with more permissions than you have).

These tokens are useful for giving access to specific people to data without exposing them to the entirety of the API. They can be created using the user/sessions API, reference docs.

Create a scoped application token

$ curl -X POST https://api.pegasusgateway.com/user/sessions \
    --header 'Content-Type: application/json' \
    --header 'Authenticate: 7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0' \
    -d '{"scheme":"infinite","app":"myApp","scopes":"groups=285&write=remote.output,tasks"}'

If you have an application token you can also use the Get user info method in order to obtain the user's information.

$ curl --request GET \
     --url 'https://api.pegasusgateway.com/user?auth=APP_TOKEN' \
     --header 'Accept: application/json'

{
  "username": "[email protected]",
  "scopes": {
    "sims": "r",
    ...
  "virtual_id": "scoped:54",
  "virtual": true,
   ...

👍

Virtual user

Get user info will respond with a virtual key that's true if the token used is an application token.
Another field virtual_id is used to refer to the originating user ID that's virtualized with the tokens permissions.

View all tokens you have created

GET /user/sessions

{
  "tokens": [
    {
      "origin": "--",
      "scopes": "groups=285&write=remote.output,tasks",
      "app": "myApp",
      "expires": 7183,
      "token": "9c56c37b52ff3b96ed0a501ac63e574fcb42c32a28c251c2a2033724",
      "app_scheme": "",
      "scheme": "finite"
    }
  ],
  "session": {
    "origin": "--",
    "scopes": "",
    "app": "None",
    "expires": 3600,
    "token": "7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0",
    "app_scheme": "",
    "scheme": "normal"
  }
}

Token limit

🚧

Limit of infinite tokens

Note that only 50 infinite tokens are allowed per account.

When you reach the limit of 50 tokens you'll get an HTTP 403 FORBIDDEN response

JSON

{
  "message": "Too many infinite tokens"
}

To fix this remove any unused token using the logout method.

Delete an application token

$ curl https://api.pegasusgateway.com/logout?auth=640c59b1df21aed608fe9cb775d56faaea9e33dd74730e31a94456e2 \
    --header 'Content-Type: application/json'

{"message": "Session terminated"}

Receiver tokens

You can also create tokens for the data receiver endpoints, a requirement in order to start receiving data on your Pegasus Gateway from third party devices, reference docs.

View receiver tokens you have created

GET /tokens

{
    "origin": "--",
    "app": "my-app",
    "token": "89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789",
    "app_scheme": "ips=12.12.12.12,13.13.13.13",
    "scheme": "infinite"
}

Create a receiver token

be sure to use an application token in the Authenticate header of the request to create the json receiver token

$ curl -X POST https://api.pegasusgateway.com/tokens \
    --header 'Content-Type: application/json' \
    --header 'Authenticate: 7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0' \
    -d '{"resource":"receivers.json","app":"my-app","app_scheme":"ips=12.12.12.12,13.13.13.13"}'

{
    "origin": "--",
    "app": "my-app",
    "token": "89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789",
    "app_scheme": "ips=12.12.12.12,13.13.13.13",
    "scheme": "infinite"
}

Delete a receiver token

curl -X DELETE https://api.pegasusgateway.com/tokens/89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789 \
    --header 'Content-Type: application/json'

Data streams

You can view the incoming data requests that use specific tokens using token streams.

The request is a GET with the /tokens/:receiver_token/stream replacing :receiver_tokens with the actual receiver token.

View incoming data for the receiver token

GET /tokens/:receiver_token/stream

{
    "size": 25,
    "items": [
        {
            "body": "[{\"vehicle.name\":\"red truck\",\"engine.hours\":4.59,\"position.altitude\":1453,\"position.heading\":179,\"position.hdop\":0.7,\"position.latitude\":6.322105,\"position.longitude\":-75.551478,\"position.satellites\":10,\"position.speed\":6,\"position.valid\":true,\"server.timestamp\":1631014478.971503,\"timestamp\":1630937864,\"vehicle.mileage\":112766.605}]",
            "url": "http://pegasus2.peginstances.com/json",
            "headers": "X-Client-Ip: 12.12.12.12\nContent-Length: 648\nAuthenticate: 89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789\nConnection: Keep-alive\nHost: cloud.pegasusgateway.com\nContent-Type: application/json\n",
            "time": "2021-09-07 11:34:39+00:00",
            "method": "POST",
            "remote_ip": "12.12.12.12"
        },
        ...

Scopes / API Permissions

A user's access to the API resources is controlled by their what groups they belong to and the scopes they have assigned.

When a user belongs to a particular group they can see all the entities (vehicles, sims, assets, devices, etc) that group has associated.

Scopes are identified by the name of the resource and then the letter's: r or w corresponding to their access level for that resource

r : read-only permissions : GET

w : read and write permissions : POST + PUT + DELETE

For example, a user with scopes: { "triggers": "r", "vehicles": "w" } has read permission for triggers and write permissions for vehicles allowing the user to only read triggers as well as create, edit, and delete vehicles

📘

Permission denied

If you don't have access to a particular resource due to scope restrictions an HTTP 401 is returned.

/user

{
  "username": "[email protected]",
  "scopes": {
    "assets": "r",
    "devices": "r",
    "geofences:visibility.all": "r",
    "geofences:visibility.groups": "r",
    "geofences": "w",
    ...

List of available scopes - resources/users/scopes