Security

How the robot API keeps robots, buildings and companies apart, what the sandbox is, and what hasn't been done yet.

Robots sign every call

Each robot has its own secret, and signs every call with it: HMAC-SHA256 over the method, the path, the time and the body (how). Nothing a robot sends works as a bearer token for someone who copies it, and a call more than 30 seconds off the gateway's clock is refused. A robot reads only its own trips, and nothing of another company's.

Secrets

• A robot's secret is shown once, when it's made: on your company's page, to the people your company signs in with. Plynth never emails one.
• Secrets start plynth_sbx_ (the sandbox) or plynth_live_ (a building), so a secret scanner can spot one in code or a log. Read-only keys start plynth_read_.
• Rotate gives a robot a new secret and keeps the old one working for 24 hours, so you can update the robot first. Revoke Old stops the old one at once, for one that leaked.
• A read-only key is for a dashboard or monitoring that reads for a robot: it makes GET calls only, and they don't count as the robot being online. Anything else answers 403, read_only_key.
• The gateway keeps each robot's secret, because it checks signatures with it. A way to sign with a key that never leaves the robot is planned.

In a building

• Off the robot's own computer, the gateway answers only HTTPS, and the robot verifies its certificate (the building's fingerprint, or the site's certificate authority).
• The gateway runs on the building's own network.
• The building's equipment keeps its own safety functions: fire recall, door safety and the way out never wait for the gateway or a robot. The gateway tells robots what's happening; it never holds a door or a car against them.
• Every request and answer goes into the building's record, hash-chained, so a changed or missing entry shows.

The sandbox

• A simulated building on one machine (Fly.io, in New Jersey). No real device, and no real building's credentials, ever.
• Companies share the building, as they would a real one. Your robots see only your trips, and your drills reach only your robots.
• The whole database resets every night at 03:00 UTC; keys and sign-ins stay.
• Requests are limited per robot and per address (the sandbox).

What hasn't been done yet

No independent audit, penetration test or certification (such as SOC 2 or ISO 27001) has been done. This page will say when one has.

Reporting a vulnerability

Write to the person at Plynth who sent you here, with Security in the subject. Please don't test against other companies' robots or keys.