API Access for a Client
Issue a client's own software a key that reads the systems at its sites and raises job requests, shown once; the sites and abilities it covers; revoking it.
API Access for a Client
Some clients run software of their own: an office system, an intranet, a facilities tool. API access lets that software read the systems you have recorded at the client's sites and ask you for work, without anyone at the client signing in to dynamik.app. You issue a key, their software presents it, and what it can see is exactly that client and nothing else.
What a Key Can Do
A key belongs to one client and carries two abilities, both ticked by default:
| Ability | What the client's software may do |
|---|---|
| Read the systems at the client's sites | List the client's sites, the systems at each (type, location, whether it is live, installation and service dates, contract type) and a system's devices by name, type, location, make and model. |
| Raise and cancel job requests | Ask you for a job at one of its sites, read your answer back, and withdraw a request you have not answered yet. |
A key never reads what an engineer reads. No user or engineer codes, no system secrets, no serial numbers, no network addresses, no configuration fields. Another client's sites do not exist as far as the key is concerned: asking for one answers not found, not forbidden.
A key is also limited to sites. All sites covers every site of the client, including ones you add later and ones the client is an associated client of. Otherwise tick the sites the key may see.
Issuing a Key
- Open the client and choose the API access tab.
- Click New key.
- Give it a Name you will recognise in the list: the software it is for, such as Dencorp Office.
- Leave both Abilities ticked unless the software only needs to read.
- Choose All sites, or Only the sites ticked below and tick them.
- Set an Expires date if the key should stop working on its own. Leave it empty for a key that lasts until you revoke it.
- Click Issue key.
The token appears once, at the top of the tab, in a field with a copy button. Copy it now and pass it to whoever runs the client's software. It is never shown again: dynamik.app keeps only a fingerprint of it, and the first twelve characters so you can tell keys apart in the list. If it is lost, revoke it and issue a new one.
A token starts with dyn_ck_. The client's software sends it on every call as Authorization: Bearer dyn_ck_…. The technical description of every call is in the API reference, under Client API.
The List
Each key shows its name, the start of its token, the sites it covers, its abilities, when it was last used and from which address, and its state: Active, Expired or Revoked (greyed, with who revoked it and when). Last used is updated at most once a minute, so a busy caller does not write on every call.
Revoking a Key
Click Revoke on the key and confirm. Every call made with it is refused from that moment, and the client's software stops working until it gets a new one. A revoked key stays in the list for the record.
Issuing and revoking are written to the client's activity log.
Requests the client raised through a revoked key are not lost. They belong to the client and its sites, not to the key: a new key sees them, and may still withdraw the pending ones.
What Happens Next
When the client's software asks for a job, the request lands on Jobs → Requests, where you approve it into a job or decline it with a reason. See Job Requests from a Client.