Skip to main content

Create Events with Device Token

Create Events with Device Token

Enable devices to create events directly with the Hyperion platform using monitorable access tokens.

Overview​

The primary use case for monitorable access tokens is enabling devices -- such as alarm panels, IoT sensors, cameras, and mobile apps -- to create events directly with the Hyperion platform without exposing partner-level credentials.

A monitorable token is scoped to a single monitorable, giving the device just enough access to report events. This is ideal for scenarios where:

  • Alarm panels need to report intrusion, fire, or panic events in real time
  • IoT sensors detect environmental changes (smoke, water, temperature) and need to notify Hyperion
  • Mobile apps allow end users to trigger manual alerts from their device
  • Connected cameras detect motion or other activity and create corresponding events

How It Works​

  1. Your backend generates a monitorable access token using your partner credentials
  2. The token is provisioned onto the device
  3. The device uses the token to create events directly via the /events endpoint
  4. Hyperion processes the event and triggers the appropriate monitoring response

Getting Started​

Before creating events with a device token, you need:

  1. An application with the monitorable:token:write and event:write scopes. If you haven't created an application yet, see the Create Application API Reference to get started.
  2. An existing monitorable to create events for. See the Monitor Persons guide if you need to create one.

Once you have your application credentials, use the Set Access Token button in the navbar to configure your partner access token for making API requests.

Step 1: Generate a Monitorable Access Token​

Events created with a device token must use a monitorable-scoped token. First, generate a token for the monitorable that will be provisioned onto the device.

Enter your monitorable ID in the path parameter field below and send the request:

Path parameters

cURL command

cURLPOST
curl -X POST "/v1/monitorables/:id/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

Upon successful generation, you'll receive an access token. Click the Copy access token button in the response to copy it to your clipboard.

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 86400
}
In a production integration, your backend would generate this token and provision it onto the device securely. The device should never have access to your partner credentials.

Step 2: Create an Event with the Device Token​

Now that you have copied the monitorable token, you can create events as the device would. An event represents an occurrence related to a monitorable, such as an alarm, alert, or status change.

To create an event, paste your monitorable access token in the field below and send a POST request to the /events endpoint with the event details:

Access token

This token will be used instead of the stored access token.

Request body

External identifier for the event. Alternatively, send the optional HTTP header External-Id when externalId is omitted or null; a string in the body takes precedence over the header.

Event type identifier

Date and time when the event was observed

Signals associated with the event

cURL command

cURLPOST
curl -X POST "/v1/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "externalId": "ext-event-12345",
  "type": "SILENT_ALERT",
  "observedAt": "2026-10-02T18:11:59.780Z"
}'

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

Upon successful creation, you'll receive a response containing the event details:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-event-12345",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "monitorableId": "550e8400-e29b-41d4-a716-446655440002",
  "systemStatus": "ACTIVE",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Conclusion​

You've successfully created an event using a monitorable device token. In a production environment, this flow allows devices to report events directly to the Hyperion platform without requiring partner-level credentials on the device itself.

Next Steps​

Learn More​

  • Events - Understanding event types and structure
  • Monitorables - Entities that events are associated with
  • Webhooks - Receiving event notifications

API Reference​