Ábyrg verslunFyrirtækiAldursskírteiniVefþjónustaAlgengar spurningar
Vefþjónusta

Tenant API Overview

Read and manage your tenant's locations, devices and employees, and read its verification transactions.

What is the Tenant API?

The Tenant API is the set of /api/v1 REST endpoints for the data your Ábyrg verslun tenant owns. Use it to keep locations, devices and employees in sync with your own systems, and to pull transaction records into your reporting. Base URL: https://abyrgverslun.is. Every path below starts with /api/.

Resources

Locations

Your stores and points of sale.

  • List, read, create, update and delete locations
  • Assign locations to devices and employees when you create them

Devices

Scanners linked through the device flow, and audit devices you create to identify a till or POS terminal.

  • List, read, update and delete devices
  • Create api-origin audit devices to attribute verifications to
  • Let a linked device read its own record (GET /api/v1/devices/me)

Employees

Staff who can attest a manual verification with their 6-digit access code.

  • List, read, create, update and delete employees
  • Look up an employee by access code (devices and service clients)

Transactions

The record of every verification that reached a decision.

  • List transactions, filtered by device, employee, location, type, result, date range or POS reference
  • Read a single transaction

Authentication

Every endpoint needs an access token in the Authorization header. Two kinds of caller use this API:

  • Service client (your backend): Authorization: Bearer <access_token>, with a token from the client_credentials grant. See Authentication.
  • Device (a linked scanner): Authorization: DPoP <access_token> plus a DPoP proof header on every request. A device token sent as Bearer is rejected with 401. See Device authentication.

The endpoints also accept dashboard user tokens. Those are internal to the dashboard and not meant for integrations. Each endpoint page lists which callers it accepts. An endpoint that doesn't accept devices answers a DPoP call with 401 or 403.

Scopes

Each endpoint needs one scope. A token without it gets 403. A resource:* scope grants both actions for that resource. Create and update calls need only the :write scope, including the record they return, and DELETE needs :write as well. Locations and employees also have a :delete scope that allows DELETE and nothing else. Reading by id or listing needs :read.

ResourceRead (GET)Write (POST, PATCH, DELETE)
Devicesdevices:readdevices:write
Locationslocations:readlocations:write (DELETE also: locations:delete)
Employeesemployees:reademployees:write (DELETE also: employees:delete)
Transactionstransactions:readtransactions:write (verifications only)

A service client's token carries the scopes registered for the client (or the subset it asked for). A device's token carries the scopes granted when it was linked: at most the store scope set, devices:read employees:read transactions:write, which is also the default. A device can't read transactions or locations, or write devices, employees or locations.

Conventions

  • Request and response bodies are JSON. Single records come back as { "data": { ... } }, lists as { "data": [ ... ] }.
  • Lists use cursor pagination: pass limit to get pages with nextCursor and hasMore. See Pagination and response conventions for the cursor rules, default sort order and how fields are formatted (createdAt is an ISO 8601 string, updatedAt is epoch milliseconds, unset fields are left out).
  • Errors use RFC 7807 Problem Details (application/problem+json). Body and query validation runs before authentication, so an invalid request gets 422 even without a token. See Errors.
  • DELETE is a soft delete: the record stops appearing in reads, and links to it (for example a device's locations) stay in place.