Evaluates the caller's current Document permission and creates an
independent session for this browser client. A caller with read-only
access receives role viewer; a caller who may edit receives editor.
The opaque admission_token lasts five minutes, is scoped to this
Document, actor, and session, and authorizes nothing on this HTTP API.
Each admission has its own token and exclusive connection lease, so
another tab cannot invalidate it. The connected relay renews the
lease; disconnected sessions expire through bounded cleanup.
The lease admits the browser-only durable Yjs relay. Raw updates,
checkpoints and awareness are not REST or SDK payloads. Resource schema
capability is checked at admission and again for each update/checkpoint.
X-Assign-Document-Schema defaults to 1. An editable schema 2 admission
promotes only this resource's envelope through its normal revision
transition, preserving opaque updates, checkpoints and replica generation.
Existing schema 1 resources continue to accept schema 1 clients.
Once promoted, schema 1 admission and already admitted schema 1 writes
fail with document_schema_version_unsupported. Invalid header values
fail with document_schema_version_unsupported. Project permissions remain authoritative.
Path Parameters
document_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001
Header Parameters
X-CSRF-TokenRequired
string·min 43·max 43
Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
X-Assign-Document-Schema
integer·default 1
Highest writable document schema supported by this client. Missing means schema 1. Editable schema 2 admission atomically promotes the resource envelope without resetting its collaboration state. Older admissions are refused after promotion.
Values
12
Responses
generation
string <uuid>
Task replica generation; an ordinary description replacement invalidates retained updates from the old generation.
idRequired
string <uuid>
Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Example0198ac5e-f9b7-7000-8000-000000000001
roleRequired
string
Values
editorviewer
admission_tokenRequired
string·min 43·max 43
expires_atRequired
string <date-time>
RFC 3339 timestamp in UTC.
Example2026-08-15T12:00:00Z
heartbeat_interval_secondsRequired
integer·min 1
Send another admission request within this interval to retain presence.
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
Retry-After
integer·min 1
Seconds until the client may retry.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Retry-After
integer·min 0
Delay in seconds before retrying, when an expected maintenance end is known.
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
