---
title: "Open an evidence session"
method: POST
path: "/api/v1/sessions"
tags: ["canonical"]
---

# Open an evidence session

`POST /api/v1/sessions`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/sessions`
- Auth: HTTP bearer

Start an enroll or observe session for a subject using the scoped browser workflow.

## Request body

- SessionCreate: Open an enrollment or observation session for the authenticated subject.
  - `device_context` object, nullable: Optional customer-provided device context, without independent device integrity attestation. Apply your endpoint controls to establish device trust.
  - `purpose` 'observe' | 'enroll': enroll collects enrollment evidence; observe assesses continuity. The default is observe.
  - `subject` string, required: Pseudonymous subject identifier in the authenticated tenant and environment.

## Response `201`

Session id, purpose, feature version, scoped signing material and research eligibility flag.

- SessionCreated: Session identifier, feature contract and short-lived evidence-signing material returned to its scoped caller.
  - `created_at` string, required: Creation time as an ISO 8601 timestamp.
  - `feature_schema_version` string, required: Version identifier for the feature representation used by the session or assessment.
  - `frame_signing_alg` string, nullable: Algorithm identifier for the session’s evidence-signing material.
  - `frame_signing_key` string, nullable: Session-specific signing secret for SDK evidence transport, when issued. Never log or expose it to another subject.
  - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
  - `purpose` string, required: Session purpose, enroll or observe.
  - `research_enabled` boolean: Environment participation and a current subject consent receipt are both present at session creation. Storage also requires deployment enablement, current consent and per-frame opt-in.
  - `subject` string, required: Pseudonymous subject identifier in the authenticated tenant and environment.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)