An integration key lets another system call the Pop Dispatch API without a person signing in. You will be able to choose a scope that matches the job and understand what a key refuses.
Before you start #
- Keys act as the person who made them. The key never reaches further than that person's role.
- The key is shown once, when it is made. Copy it into the other system straight away.
The four scopes #
| Scope | What it allows |
|---|---|
| user | What the person's role allows. Sign-in tokens carry this scope. |
| full | The same reach as user. |
| read | Reading only: GET and HEAD calls. Every write answers "This key is read-only." |
| dispatch | Towing and the driver app, plus reading customers and vehicles. Everything else answers "This key is for towing dispatch only." |
The dispatch scope covers paths under /tow and /driver, /me, and read access to /customers and /vehicles.
Steps #
- Open Settings, Integration keys and choose to make a key.
- Name it after the system that will use it, for example "Motor club feed".
- Choose the narrowest scope that does the job. A reporting tool needs read. A call-taking system needs dispatch.
- Copy the key. It starts with
psdt_. - In the other system, send it as
Authorization: Bearer <key>.
Checks on every request #
- The key is well formed and known.
- It is still valid: neither revoked nor past its end date.
- The person who owns it is still active.
- The person's role allows the area.
- The scope allows the method and path.
- While the licence is read-only, writes answer
licence_read_only.
Technical details
- Keys are
psdt_plus 39 letters and digits (44 characters). The server stores a SHA-256 hash and a display prefix (the first 8 characters). - A key has a name, a platform, a scope, an end date or none, a last-used time and a last-used address.
- An integration key keeps the lifetime you chose. A sign-in token renews itself when 30 days or fewer remain.
- Every key is limited to 300 requests a minute, and every network address to 600.
- Backups never contain token hashes. After a restore, make new keys. See "Backups and restore".
If something goes wrong #
forbidden(403) "This key is read-only.": use a user or full key for writes.forbidden(403) "This key is for towing dispatch only.": the call is outside the dispatch scope.unauthorized(401): the key ended, was revoked or belongs to an inactive account.