Resource model

The platform exposes a small set of resources. Understanding how they relate is enough to build almost any solution on top.

The resources

• Team — who owns things. Your integration authenticates as a team. A team can create subteams beneath it, so you can give each customer or tenant its own isolated space and its own key.
• API key — how a team authenticates. A key belongs to exactly one team and only ever sees that team’s data.
• Tag — the digital identity bound to a physical item. Tags belong to a team. A tag is what gets scanned.
• Session — one verification flow against a tag. A session groups the scans that make up a single check.
• Verification — the verdict for a scan: pending, valid, or invalid. Verifications belong to a session.

How they relate

Team ──┬── owns ──▶ API key   (one team, many keys)
       └── owns ──▶ Tag       (one team, many tags)

Tag ──── has ──▶ Session ──── has ──▶ Verification
                 (one scan flow)      (the verdict)

• A team owns its tags and its API keys.
• A tag accumulates sessions — one per scan flow.
• A session holds the verifications produced as the flow resolves: a pending, later upgraded to valid or invalid.

Subteams: multi-tenant by design

Teams nest. The team that owns your API key is your root team; every team you create through the API becomes a subteam of it, with a fresh key of its own.

This is the tenancy primitive. A solution typically provisions one subteam per end customer, stores that subteam’s key, and provisions that customer’s tags under it. Because a key only sees its own team’s tags, tenants are isolated from each other automatically — a scan validated with one subteam’s key can only ever resolve a tag that subteam owns.

Teams and subteams exist for two reasons:

• Sandbox separation. Sandbox is a property of the team, never of an individual tag. A team is either a sandbox team or a production team, so production tags and sandbox tags can never appear side by side in the same team.
• Billing and quota boundaries. A team is the unit a bill attaches to — a team could be a company, a customer, a legal entity. A multi-tenant solution that needs separate billing per tenant is structured correctly by giving each tenant its own team.

Teams are strict access boundaries, and access is never inherited: a dashboard user sees only the teams they are a member of. Root-team membership grants nothing on its subteams — each membership is granted per team, explicitly.

Identifiers

Every resource has a prefixed, URL-safe id you’ll see throughout the API:

The prefix tells you the type at a glance; treat the whole string as an opaque identifier.