# Sessions

The unit that groups related scans into one verification flow.


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

| Field         | Type   | Notes                                       |
|---------------|--------|---------------------------------------------|
| `id`          | string | `ses_`-prefixed, assigned by the platform.  |
| `inserted_at` | string | ISO 8601 timestamp when the session opened. |

A session belongs to a [tag](/docs/api/tags) and groups the
[verifications](/docs/api/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`:

```json
"relationships": {
  "session": { "data": { "type": "sessions", "id": "ses_2cZuH8Cb7L5fseae6FzNDc" } }
}
```

## 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:

```json
"relationships": {
  "session": { "data": { "type": "sessions", "id": "ses_2cZuH8Cb7L5fseae6FzNDc" } }
}
```

See [Verifications → Sessions and resolution](/docs/api/verifications) for the
full sequence.

A session is live for its tag's `session_duration`: **10 minutes** unless you
[configured the tag](/docs/api/tags) otherwise. 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](/docs/api/tags) as a relationship. The key
you present must own that tag, or the platform responds `404`.

<!-- tabs -->
```bash cURL
curl https://platform.tagbase.io/api/v1/sessions/ses_2cZuH8Cb7L5fseae6FzNDc \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Accept: application/vnd.api+json"
```
```js
const res = await fetch(
  "https://platform.tagbase.io/api/v1/sessions/ses_2cZuH8Cb7L5fseae6FzNDc",
  {
    headers: {
      "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
      "Accept": "application/vnd.api+json",
    },
  },
);
const session = await res.json();
```
```php
$response = $client->get("https://platform.tagbase.io/api/v1/sessions/ses_2cZuH8Cb7L5fseae6FzNDc", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Accept"        => "application/vnd.api+json",
    ],
]);
$session = json_decode((string) $response->getBody(), true);
```
```elixir
session =
  Req.get!("https://platform.tagbase.io/api/v1/sessions/ses_2cZuH8Cb7L5fseae6FzNDc",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"accept", "application/vnd.api+json"}
    ]
  ).body
```
<!-- /tabs -->

### Response: `200 OK`

```json
{
  "data": {
    "type": "sessions",
    "id": "ses_2cZuH8Cb7L5fseae6FzNDc",
    "attributes": { "inserted_at": "2026-06-08T12:34:56.123456Z" },
    "relationships": {
      "tag": { "data": { "type": "tags", "id": "tag_XPg3Zq7gEExNezDWWW7Zzo" } }
    }
  }
}
```

### Errors

| Status | When                                |
|--------|-------------------------------------|
| `401`  | Missing, invalid, or revoked key.   |
| `404`  | No such session under your team. |

## 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.