REST API

Manage1to1 includes a REST API so your district can connect your own reporting, dashboards, and automations. You can read your data (devices, users, buildings, tickets, incidents, invoices, and custom fields) and, when you grant the permission, write it too — create and update devices and users, open and update tickets, log incidents, and create invoices and record payments.

Access is controlled by tokens that you issue yourself. Each token is limited to exactly what you allow — which areas, and whether it may only read or also make changes — and can only be used from network locations you approve, so you decide precisely what any integration can reach.

Every change is attributed

Actions a token takes are recorded in your Activity Log so a change made by an integration is just as traceable as one made by a person in the admin area. A user token attributes its changes to the administrator who created it. A global (service) token, shared by an integration that acts for several people, instead names the specific person behind each change — see Choosing a token type below. Create operations also support safe retries, so a dropped connection won't accidentally create something twice.

Your interactive reference lives inside the app

Every instance hosts its own interactive API documentation, kept perfectly in step with your version. You can browse every available endpoint, see the exact fields returned, and try live requests right from the page. This guide covers how to issue a token and where to find that reference. Open API Docs from the console for the endpoint details themselves.

Finding the API Console

Go to Settings → API Tokens.

From here you can:

• Issue a new token with a name, a set of permissions, and approved network locations
• Review existing tokens: their name, permissions, when they were last used, and when they expire
• Revoke a token the moment it is no longer needed
• Open the API Docs, the interactive reference for your instance

Issuing a Token

Select Create Token and complete the form:

1. Name: a short, recognizable label (for example, State reporting export or Nightly device sync) so you can tell your tokens apart later.
2. Token type: choose a user token (the default — it acts as you) or a global service token shared by an integration that acts on behalf of several people. See Choosing a token type.
3. Permissions: choose only what this token may do. Permissions are grouped by area (devices, users, buildings, tickets, incidents, invoices, custom fields, and more) and split into read and write — so a token can be read-only, or allowed to make specific kinds of changes. A token can never do more than the permissions you grant it.
4. Approved locations: enter the network locations allowed to use this token. This is required. A token with no approved location cannot be used at all.
5. Expiration: every token has an expiry date, so access never lingers indefinitely.

Copy your token immediately

For your security, the full token is shown only once, at the moment you create it. Copy it and store it somewhere safe right away. If you lose it, you cannot see it again. Simply revoke it and issue a new one.

Approved Locations

Every token is tied to the network locations allowed to use it. We strongly recommend listing single addresses (the specific locations your integration actually runs from) rather than broad ranges.

• Single addresses are entered directly, one per line.
• Ranges are supported when a single address isn't practical, but only up to a modest span. Very broad ranges are rejected, so a token can never be usable from anywhere on the internet.

If a request arrives from a location that isn't on the token's approved list, it is refused before any data is returned.

Choosing a Token Type

Every token is one of two types, and the choice only affects who each change is attributed to in your Activity Log:

• User token (the default). The token acts as the administrator who created it, and everything it does is recorded against that person. This is the right choice for a token that represents one individual's automation.
• Global (service) token. Meant for an integration shared by several people — a help-desk tool, a state-reporting bridge, a self-service portal. Because many different people act through the one token, it must tell Manage1to1 who is behind each change that it makes, so your Activity Log names the real person rather than the token.

A global token names the acting person by including their email address in an X-Initiating-User request header on each change it submits. The email must belong to an active administrator on your instance; if it is missing or unrecognized, the change is refused rather than recorded against the wrong person. Read-only requests don't require it.

Newer API version

User attribution for global tokens is part of version 2 of the API. Your in-app API Docs always show the current version and the exact header to send. Existing integrations on the previous version keep working unchanged.

Choosing Permissions Well

The safest token is the one that can do the least. When you set up an integration, grant only the permissions it genuinely needs — and prefer read over write unless the integration truly needs to make changes:

• A reporting export that only charts data needs read access to those areas, nothing more.
• A help-desk dashboard needs only ticket and incident read access.
• An integration that opens tickets needs ticket write; a device-inventory sync that creates devices needs device write.

If an integration's needs change later, issue a new token with the right permissions and revoke the old one.

Sensitive data is flagged

Some permissions grant access to personal information about students and staff. These are clearly marked when you choose permissions, so you can be deliberate about which tokens are allowed to read them.

Keeping an Integration in Sync

Most integrations don't need the whole picture every time they run. A nightly device export, a dashboard that refreshes through the day, or an automation that reacts to changes only needs what has changed since it last checked.

Every list of records the API returns can be narrowed to just the records modified on or after a moment in time. So instead of pulling every device or every user on each run, your integration can ask only for what changed since the last time it ran, which is dramatically faster and lighter on both sides. Each record also reports when it was last modified, so your integration can remember that point and pick up exactly where it left off next time.

This works across the board: devices, users, buildings, tickets, incidents, invoices, and more. A common example is a device sync that keeps an external system current as devices move between locations, change status, or get reassigned. Rather than reconciling your entire fleet every night, it pulls only the handful of devices that actually changed that day.

Your in-app API Docs show the exact option to use on each list, along with the field that reports when a record was last modified, and let you try it live.

Webhooks: Get Notified of Changes

Polling (asking the API what changed since last time) works well for scheduled syncs, but sometimes you want to know the moment something happens. Webhooks let Manage1to1 call your system, so an integration can react to an event the instant it occurs instead of waiting for its next run.

You register a webhook from the API using a token that has the Manage webhook subscriptions permission. Each subscription has:

• A destination URL, which must be a public HTTPS address. For your protection, internal and private addresses are refused, so a webhook can never be pointed at something inside your own network.
• The events it should receive. You can pick exactly the ones you care about, or subscribe to everything.

Events You Can Subscribe To

• Devices: created, updated, assigned (checked out), and checked in
• Tickets: created, updated, and replied to
• Incidents: created and updated
• Invoices: created and paid

When a subscribed event happens, Manage1to1 sends your URL a request whose body describes what occurred. Your in-app API Docs list every event and show the shape of each message.

Reliable Delivery

If your endpoint is briefly unreachable or returns an error, Manage1to1 does not drop the notification. It retries automatically, waiting a little longer between each attempt, for a period of time before giving up. Every attempt (and the response your endpoint returned) is recorded in a delivery log you can review through the API, so a notification that never arrived is easy to spot and understand. You can also send a test delivery to a subscription at any time to confirm your endpoint is receiving and handling messages correctly.

Verifying a Webhook Is Genuine

Because your endpoint is a public URL, you should confirm that each request really came from Manage1to1 and was not altered in transit. Every delivery includes these headers:

• X-Manage1to1-Signature: a signature of the message, prefixed with sha256=
• X-Manage1to1-Timestamp: when the message was sent
• X-Manage1to1-Event: the event type the message represents

Each subscription has its own signing secret, shown to you once when you create the subscription (keep it somewhere safe, exactly like a token). To verify a request, compute an HMAC-SHA256 using your signing secret as the key, over the timestamp header, followed by a period, followed by the exact request body. Prefix the result with sha256= and compare it to the signature header. If they match, the request is authentic. To protect against a captured request being replayed later, also reject any request whose timestamp is older than a few minutes.

Keep the secret and the URL private

Anyone who knows a subscription's signing secret could forge a request your system would trust, and any HTTPS URL that leaks could receive your event data. Treat both like a password: store them securely, and if either is ever exposed, delete the subscription and create a new one.

Revoking a Token

If a token is no longer used, or you suspect it has been exposed, revoke it from Settings → API Tokens. Revocation takes effect immediately, and any further requests using that token are refused at once. Issue a fresh token for anything that still needs access.