JSON session instructions

The registration response body, and an optional refresh response body, that declares identity, scope, protected cookies, and refresh policy.

Syntax

The body is JSON. At registration, session_identifier, scope, and credentials are required unless continue is false; this creation path has a null prior session ID. On refresh, an included identifier must equal the existing current ID.

{
  "session_identifier": "session-42",
  "refresh_url": "/dbsc/refresh",
  "scope": {"origin":"https://app.example","include_site":false,"scope_specification":[]},
  "credentials": [{"type":"cookie","name":"sid","attributes":"Path=/; Secure; HttpOnly; SameSite=Lax"}],
  "allowed_refresh_initiators": []
}

Fields and constraints

Instruction field inventory
Item	Requirement / behavior
`session_identifier`	String; required at registration unless terminating; equality required on refresh.
`refresh_url`	Optional absolute or relative string; defaults to the URL serving instructions; resolved URL must be HTTPS/localhost and same-site.
`continue`	Optional boolean, default `true`. `false` removes an existing refresh session; with registration’s null prior ID, termination is a no-op and no session is created.
`scope.origin`	Optional origin string, default instruction URL origin; must be valid, non-opaque, same-site with destination.
`scope.include_site`	Required boolean: `false` origin scope, `true` site scope. Site scope has extra root-domain and well-known checks.
`scope.scope_specification`	Optional ordered rule list; later rules win. Rule `type` is required `include`/`exclude`; domain defaults `*`, path defaults `/`.
`credentials`	Required list; current type must be `cookie`, nonempty `name`; `attributes` defaults empty. `Partitioned` is forbidden.
`allowed_refresh_initiators`	Optional string host patterns; defaults empty; limits out-of-scope initiators that may trigger refresh.

Outputs and cookie interaction

The browser stores a session only if at least one declared credential could be set by the response. A request needing an applicable declared cookie is deferred when that cookie is absent. Matching considers name and cookie attributes Domain, Path, Secure, HttpOnly, and SameSite; Max-Age/Expires do not determine satisfaction.

Errors and validation

Invalid JSON, missing required keys, bad origins/URLs, non-cookie credential type, disallowed Partitioned attribute, mismatched refresh ID, invalid scope, or inability to set every applicable cookie invoke the draft termination step. With the null ID used for registration, termination is a no-op: no DBSC session is created or replaced. With a non-null refresh ID, the existing DBSC session is removed. Unknown JSON members are not a documented extension mechanism; do not depend on them.

Context

Serve with JSON after the registration POST; a refresh can return an empty body to retain the old config, or JSON to replace it. Cookies still obey normal cookie storage and request rules. The refresh URL itself is excluded from the session’s protected scope to avoid recursion.

Scope and expiry

For a URL, the browser first requires same origin/site according to include_site, excludes the refresh URL, then evaluates scope rules from last to first. Session lifetime is browser-selected and recommended to align with maximum cookie lifetime; do not assume a fixed timer. A response with continue:false removes an existing refresh session, but during null-ID registration it creates nothing and the terminate step is a no-op.

Complete registration body

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Set-Cookie: sid=short-token; Path=/; Max-Age=600; Secure; HttpOnly; SameSite=Lax

{"session_identifier":"session-42","refresh_url":"/dbsc/refresh","scope":{"origin":"https://app.example","include_site":false,"scope_specification":[{"type":"exclude","path":"/public"}]},"credentials":[{"type":"cookie","name":"sid","attributes":"Path=/; Secure; HttpOnly; SameSite=Lax"}],"allowed_refresh_initiators":[]}

Compatibility

DBSC availability and standards position
Item	Requirement / behavior
Chrome	DBSC availability, not page-layout support: ChromeStatus lists DBSC as in development, with Chrome desktop milestone 145. Its Android milestone is null/unknown; availability remains controlled by implementation and feature configuration.
Firefox	No signal; the Mozilla standards-position issue is the public evidence, not an implementation commitment.
Safari	No signal; the WebKit standards-position issue is the public evidence, not an implementation commitment.
Other engines	Unknown. The W3C document is an Editor’s Draft, not a final interoperable Recommendation.

Security and privacy

Keep scope as narrow as the protected session permits. Never use DBSC to bypass SameSite, third-party-cookie, or partitioning policy. Use allowed_refresh_initiators to limit cross-site refresh timing leakage; the draft explicitly calls out that side channel.

Primary sources: json · algorithms · create-session algorithm · URL-in-scope algorithm · missing-credential algorithm · chrome · security · rfc9651. External sources open in a new tab.