Getting Started / Authentication

Overview

This guide covers how to authenticate with the Pegasus Gateway API and manage access tokens securely. The API uses token-based authentication: you exchange credentials for a session token, then include that token in all subsequent requests.

Key concepts:

Session tokens — Short-lived tokens obtained via login. They expire after 60 minutes of inactivity.
Application tokens — Scoped, long-lived tokens for integrations. They follow the principle of least privilege by restricting access to only the resources you specify.
Receiver tokens — Special-purpose tokens for ingesting data from third-party devices.

⚠️
Security Best Practice
Rotate tokens regularly and always grant the minimum permissions necessary. Prefer finite (time-limited) tokens over long-lived ones. Revoke tokens immediately when they are no longer needed.

Authentication

Authenticate using the login endpoint to obtain a session token. There are two authentication methods:

Method	Endpoint	Required Parameters
Central Auth Server	`https://auth.pegasusgateway.com/`	`username`, `password`, `gateway`
Pegasus Domain URL	`https://yourpegasusdomain.com/api/login`	`username`, `password`

Central Auth:

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

Domain URL:

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

Response

A successful login returns a session token in the auth field:

{
  "message": "User successfully authenticated",
  "app": null,
  "auth": "208b....a0ce"
}

👍
Include the token in every subsequent request using the HTTP header Authenticate

Session tokens expire after 60 minutes of inactivity by default. This is by design — short-lived tokens reduce the risk of unauthorized access if a token is compromised.

Get User Info

Retrieve the authenticated user's profile and permissions:

curl --request GET \
     --url 'https://api.pegasusgateway.com/user' \
     --header 'Authenticate: AUTH_SESSION_TOKEN'

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

For information on embedding applications in Pegasus, see Applications.

Application Tokens

Application tokens provide scoped, restricted access to the API. Use them to grant integrations or third parties access to only the specific resources they need — without exposing your full account permissions.

Key principles:

An application token cannot exceed the permissions of the user who created it.
Always scope tokens to the minimum required groups and permissions.
Rotate tokens periodically — revoke old tokens and issue new ones on a regular schedule.
Name tokens descriptively (via the app parameter) so you can audit and manage them.

Creating an Application Token

Use the POST /user/sessions endpoint:

Parameter	Description
`scheme`	`finite`
`limit`	Token lifetime in seconds
`app`	Descriptive name for the token (e.g., `"fleet-dashboard"`)
`scopes`	Access restrictions in URL param format: `groups=<IDs>&read=<scopes>&write=<scopes>`
`app_scheme`	Reserved for Pegasus platform applications

Example — Create a scoped token:

curl -X POST https://api.pegasusgateway.com/user/sessions \
    --header 'Content-Type: application/json' \
    --header 'Authenticate: 7ebb...12c0' \
    -d '{"scheme":"finite","limit":86400,"app":"fleet-dashboard","scopes":"groups=285&write=remote.output,tasks"}'

Response:

{
  "origin": "--",
  "scopes": "groups=285&write=remote.output,tasks",
  "app": "fleet-dashboard",
  "token": "af11...cef5",
  "app_scheme": "",
  "user": 1,
  "scheme": "finite"
}

Verifying an Application Token

Call Get user info with an application token to confirm its effective permissions:

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: When virtual is true, the token is an application token. The virtual_id identifies the originating user whose permissions are being virtualized.

List all your tokens:

GET /user/sessions

{
  "tokens": [
    {
      "origin": "--",
      "scopes": "groups=285&write=remote.output,tasks",
      "app": "fleet-dashboard",
      "expires": 7183,
      "token": "9c56...3724",
      "app_scheme": "",
      "scheme": "finite"
    }
  ],
  "session": {
    "origin": "--",
    "scopes": "",
    "app": "None",
    "expires": 3600,
    "token": "7ebb...12c0",
    "app_scheme": "",
    "scheme": "normal"
  }
}

Revoke a token:

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

{"message": "Session terminated"}

🔐
Token hygiene: Regularly audit your active tokens via GET /user/sessions and revoke any that are no longer in use. Accounts are limited to 50 long-lived tokens — if you hit this limit, it indicates tokens are not being properly rotated or cleaned up.

Receiver tokens

Receiver tokens authorize the data receiver endpoints to accept data from third-party devices into your Pegasus Gateway.

Parameter	Description
`resource`	The data receiver endpoint (e.g., `receivers.json`)
`app`	Descriptive name for the receiver
`app_scheme`	IP allowlist/blocklist config: `ips=<CSV of IPs>` and optionally `ips_blacklist=1` to treat the list as a blocklist

🔐
Always restrict receiver tokens by IP address using the app_scheme parameter. This ensures only known sources can send data to your gateway.

Create a receiver token:

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

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

List receiver tokens:

GET /tokens

Delete a receiver token:

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

Data Streams

Monitor incoming requests for a specific receiver token:

GET /tokens/:receiver_token/stream

{
  "size": 25,
  "items": [
    {
      "body": "[{\"vehicle.name\":\"red truck\",\"engine.hours\":4.59,\"position.altitude\":1453,...}]",
      "url": "http://pegasus2.peginstances.com/json",
      "headers": "X-Client-Ip: 12.12.12.12\nContent-Length: 648\nAuthenticate: 89bf...6789\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"
    }
  ]
}

{
    "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: 89bf...6789\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

API access is governed by two mechanisms:

Groups — Determine which entities (vehicles, SIMs, assets, devices) a user can see.
Scopes — Determine what actions a user can perform on each resource type.

Permission Levels

Level	HTTP Methods	Description
`r`	GET	Read-only access
`w`	GET, POST, PUT, DELETE	Full read/write access

Example: A user with { "triggers": "r", "vehicles": "w" } can view triggers but can create, edit, and delete vehicles.

📘
Permission denied: Attempting to access a resource without the required scope returns HTTP 401 Unauthorized.

Retrieve the full list at resources/users/scopes. Below is the complete reference:

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

Security Recommendations

Practice	Why
Always use finite tokens	Limits exposure window if a token is compromised
Rotate tokens regularly	Reduces risk from leaked or stale credentials
Scope tokens narrowly	Prevents accidental or malicious access to unrelated resources
Restrict receiver tokens by IP	Ensures only trusted sources can send data
Audit tokens periodically (`GET /user/sessions`)	Identifies orphaned or unnecessary tokens to revoke
Revoke unused tokens immediately	Minimizes your active attack surface