Getting Started

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.

11661166

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:

methodvalue
HTTP HeaderAuthenticate
URL Path Parameterauth

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.

paramdescription
schemeinfinite or finite token
limitlimit of token in seconds
appcustom app name
scopesurl param format, params: groups allowing to write a csv of group IDs that the token will have access to, and any scope using the params write or read and setting these equal to a csv of the scopes you want to be able to write/read
app_schemepegasus application use only

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"
  }
}

🚧

Limit of infinite tokens

Note that only 50 infinite tokens are allowed per account. To remove a token use 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.

paramdescription
resourceset to the data receiver (so far: receivers.json)
appcustom app name
app_schemeurl param format, params: ips which is a CSV of ip addresses to allow data from, and ips_blacklist when set to 1 the list of ips is treated as a blacklist.

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

resourcepermissiondescriptionAPI
assets:trackerwriteallows asset trackers the ability to update checkpoints (geofences) (used in Taurus App)
assetsreadsee the assets (drivers, things, etc)assets
assetswritecreate and edit assets (drivers, things, etc)assets
configurationsreadread the managed configurationsconfigurations
device.mutereadview event mute statusdevices
device.mutewritemute device eventsdevices
devicesreadview devicesdevices
deviceswritecreate devices is not available, contact support
entities.linkwriteassociate or disassociate two entitiesentities
formswriteview and fill out forms assigned to this user
forwardersreadview forwarder statusforwarders
forwarderswritecontact support to create forwarders
geofencesreadview own geofencesgeofences
geofenceswritecreate and edit your own geofencesgeofences
geofences:adminwriteallows user to modify any geofence within their group even if another owner owns it
geofences:visibilitywriteview public geofencesgeofences
geofences:visibility.allwritecreate public geofencesgeofences
geofences:visibility.groupswritecreate geofences for your groupgeofences
groupsreadread the groups and its' infogroups
groupswritecreate and edit groupsgroups
groups.assetswritemanage assets within your groupassets
groups.userswritemanage users within your groupusers
groups.vehicleswritemanage vehicles within your groupvehicles
pindropswritecreate a pindrop (safe zone) around an entitypindrops
plugins.garminreadsee garmin jobs & messagesplugins.garmin
plugins.garminwritecreate garmin jobs and send garmin messagesplugins.garmin
plugins.lumewayreadread the lumeway dataplugins.lumeway
plugins.lumewaywritetake a photo with the lumeway accessoryplugins.lumeway
plugins.photocamreadsee the photosphotos
plugins.photocamwritetake photosphotos
plugins.satcomreadsee satcom parameterssatcom
plugins.satcomwriteset satcom parameterssatcom
rawdatareadget the vehicle's rawdatarawdata
remotereadsee the remote GET methodsremote
remotewriteability to execute all remote commands (the dot commands below)remote
remote.callwritecall an authorized numberremote
remote.configurationwriteset a managed configurationremote
remote.consolewritesend console (freestyle) commandsremote
remote.diagnosticwriteable to send the diagnostic command that connects the device to diagnostic portal
remote.ecu_consolewriteable to send the query for updating ecu monitor variables
remote.fwupdatewriteexecute a firmware updateremote
remote.gps_statuswriteable to send a diagnostic message for the gps of syrus devices
remote.ky_resetwriteable to resync a managed configuration
remote.mdtwritesend mdt (serial port) messagesremote
remote.outputwriteset an outputremote
remote.outputsetlogreadview the output activation logs
remote.phoneswriteauthorize a numberremote
remote.rpmwriteset rpm thresholdremote
remote.safe_immowriteexecute a safe engine immobilizationremote
remote.segmentswriteconfigure the segments for an entitySegments (Trips)
remote.sms_aliaswriteset an sms_alias for actionsremote
remote.speedwriteset a speed limit thresholdremote
remote.statereadview the state of the inputs/outputs of a device
remote.tracking_resolutionwriteset tracking resolutionremote
remote.trigger_position_eventwritequery device's live locationremote
routesreadsee entity routesroutes
routeswritecreate routesroutes
simsreadsee the SIMs infosims
sims:subaccountsreadallows to manage wireless and super sims
tasksreadview a tasktasks
taskswritecreate/edit a tasktasks
triggersreadsee the triggers assigned to your usertriggers
triggerswritecreate and edit triggerstriggers
users.application_datareadview permissions for other usersusers
users.application_datawriteassign permissions for other usersusers
users.password_resetwriteset or reset the password of other usersusers
usersreadread the user's infousers
userswritecreate and edit the usersusers
vehiclesreadread the vehicle list and it's informationvehicles
vehicleswritecreate and edit a vehiclevehicles
vehicles.countersreadread the vehicle's countersvehicle-counters
vehicles.counterswriteedit the global vehicle countersvehicle-counters

Did this page help you?