Sessions

A session represents a single verification flow against one tag. It’s the thread that connects one scan to the next so the platform can resolve them into one verdict.

Fields

A session belongs to a tag and groups the verifications produced as the flow resolves — a pending, then its valid / invalid resolution.

Where sessions come from

You don’t create a session directly. The platform opens one for you when a scan arrives without a session relationship and returns its id in the verification response, under data.relationships.session:

"relationships": {
  "session": { "data": { "type": "sessions", "id": "ses_abcdef0123456789" } }
}

Using a session

Carry that session id back as the session relationship on a later scan so the platform continues the session rather than starting a new flow:

"relationships": {
  "session": { "data": { "type": "sessions", "id": "ses_abcdef0123456789" } }
}

See Verifications → Sessions and resolution for the full sequence.

A session is live for 10 minutes. A scan after that window opens a fresh session instead of resolving the old one.

Retrieve a session

GET /api/v1/sessions/:id

Fetch a session by id, with its tag as a relationship. The key you present must own that tag, or the platform responds 404.

curl https://platform.tagbase.io/api/v1/sessions/ses_abcdef0123456789 \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Accept: application/vnd.api+json"

const res = await fetch(
  "https://platform.tagbase.io/api/v1/sessions/ses_abcdef0123456789",
  {
    headers: {
      "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
      "Accept": "application/vnd.api+json",
    },
  },
);
const session = await res.json();

$response = $client->get("https://platform.tagbase.io/api/v1/sessions/ses_abcdef0123456789", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Accept"        => "application/vnd.api+json",
    ],
]);
$session = json_decode((string) $response->getBody(), true);

session =
  Req.get!("https://platform.tagbase.io/api/v1/sessions/ses_abcdef0123456789",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"accept", "application/vnd.api+json"}
    ]
  ).body

Response — 200 OK

{
  "data": {
    "type": "sessions",
    "id": "ses_abcdef0123456789",
    "attributes": { "inserted_at": "2026-06-08T12:34:56.123456Z" },
    "relationships": {
      "tag": { "data": { "type": "tags", "id": "tag_abcdef0123456789" } }
    }
  }
}

Errors

Notes

• A session can be fetched by id (above); there is no endpoint to list sessions. Otherwise it appears only as a relationship on a verification. Hold the id on your side for as long as the flow runs.