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:
method | value |
---|---|
HTTP Header | Authenticate |
URL Path Parameter | auth |
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",
...
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.
param | description |
---|---|
scheme | infinite or finite token |
limit | limit of token in seconds |
app | custom app name |
scopes | url 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_scheme | pegasus 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'strue
if the token used is an application token.
Another fieldvirtual_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
{ "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.
param | description |
---|---|
resource | set to the data receiver (so far: receivers.json ) |
app | custom app name |
app_scheme | url 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
{
"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.
{
"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
resource | permission | description | API |
---|---|---|---|
assets:tracker | write | allows asset trackers the ability to update checkpoints (geofences) (used in Taurus App) | |
assets | read | see the assets (drivers, things, etc) | assets |
assets | write | create and edit assets (drivers, things, etc) | assets |
configurations | read | read the managed configurations | configurations |
device.mute | read | view event mute status | devices |
device.mute | write | mute device events | devices |
devices | read | view devices | devices |
devices | write | create devices is not available, contact support | |
entities.link | write | associate or disassociate two entities | entities |
forms | write | view and fill out forms assigned to this user | |
forwarders | read | view forwarder status | forwarders |
forwarders | write | contact support to create forwarders | |
geofences | read | view own geofences | geofences |
geofences | write | create and edit your own geofences | geofences |
geofences:admin | write | allows user to modify any geofence within their group even if another owner owns it | |
geofences:visibility | write | view public geofences | geofences |
geofences:visibility.all | write | create public geofences | geofences |
geofences:visibility.groups | write | create geofences for your group | geofences |
groups | read | read the groups and its' info | groups |
groups | write | create and edit groups | groups |
groups.assets | write | manage assets within your group | assets |
groups.users | write | manage users within your group | users |
groups.vehicles | write | manage vehicles within your group | vehicles |
pindrops | write | create a pindrop (safe zone) around an entity | pindrops |
plugins.garmin | read | see garmin jobs & messages | plugins.garmin |
plugins.garmin | write | create garmin jobs and send garmin messages | plugins.garmin |
plugins.lumeway | read | read the lumeway data | plugins.lumeway |
plugins.lumeway | write | take a photo with the lumeway accessory | plugins.lumeway |
plugins.photocam | read | see the photos | photos |
plugins.photocam | write | take photos | photos |
plugins.satcom | read | see satcom parameters | satcom |
plugins.satcom | write | set satcom parameters | satcom |
rawdata | read | get the vehicle's rawdata | rawdata |
remote | read | see the remote GET methods | remote |
remote | write | ability to execute all remote commands (the dot commands below) | remote |
remote.call | write | call an authorized number | remote |
remote.configuration | write | set a managed configuration | remote |
remote.console | write | send console (freestyle) commands | remote |
remote.diagnostic | write | able to send the diagnostic command that connects the device to diagnostic portal | |
remote.ecu_console | write | able to send the query for updating ecu monitor variables | |
remote.fwupdate | write | execute a firmware update | remote |
remote.gps_status | write | able to send a diagnostic message for the gps of syrus devices | |
remote.ky_reset | write | able to resync a managed configuration | |
remote.mdt | write | send mdt (serial port) messages | remote |
remote.output | write | set an output | remote |
remote.outputsetlog | read | view the output activation logs | |
remote.phones | write | authorize a number | remote |
remote.rpm | write | set rpm threshold | remote |
remote.safe_immo | write | execute a safe engine immobilization | remote |
remote.segments | write | configure the segments for an entity | Segments (Trips) |
remote.sms_alias | write | set an sms_alias for actions | remote |
remote.speed | write | set a speed limit threshold | remote |
remote.state | read | view the state of the inputs/outputs of a device | |
remote.tracking_resolution | write | set tracking resolution | remote |
remote.trigger_position_event | write | query device's live location | remote |
routes | read | see entity routes | routes |
routes | write | create routes | routes |
sims | read | see the SIMs info | sims |
sims:subaccounts | read | allows to manage wireless and super sims | |
tasks | read | view a task | tasks |
tasks | write | create/edit a task | tasks |
triggers | read | see the triggers assigned to your user | triggers |
triggers | write | create and edit triggers | triggers |
users.application_data | read | view permissions for other users | users |
users.application_data | write | assign permissions for other users | users |
users.password_reset | write | set or reset the password of other users | users |
users | read | read the user's info | users |
users | write | create and edit the users | users |
vehicles | read | read the vehicle list and it's information | vehicles |
vehicles | write | create and edit a vehicle | vehicles |
vehicles.counters | read | read the vehicle's counters | vehicle-counters |
vehicles.counters | write | edit the global vehicle counters | vehicle-counters |
Updated over 1 year ago