Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

QR table access and ordering

Claim approved native table membership

POST/public/table-joins/{joinId}/claim

Claims an approved current-session join exactly once into its native operational guest slot. Retained presentation provenance is reauthorized without requiring a widget bootstrap proof. The original capability is encrypted for retry and disclosed again only while that original membership and presentation authority remain current. A new key never issues a second membership for an already claimed join. A required Idempotency-Key makes retries with the same payload return the stored status and body; reusing the key with a different payload returns 409.

Authentication

Authorization: Bearer <HALLIFY_TABLE_JOIN_TOKEN>

Guest-owned capability for one table join request, bound to its venue, session, presentation resource and browser origin. It grants no table membership before the native claim succeeds.

Connection guide

Parameters

joinIdPath · Required

Native table admission request whose decision or claim state is addressed. Its original venue, session and presentation provenance remain fixed.

string · uuid
Full definition
{
  "format": "uuid",
  "type": "string",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}
idempotency-keyHeader · Required

Required idempotency key, up to 128 characters

string
Full definition
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "example": "example"
}
originHeader · Required

Actual browser-managed request origin used to validate approved presentation provenance and its current resource binding. Browser clients preserve this value; the separate join or membership credential supplies guest authorization.

string · uri
Full definition
{
  "type": "string",
  "format": "uri",
  "example": "https://example.test/resource"
}

Responses

200Original private table-session membership capability and its native scope.
TablePublicMembershipCreatedDto
Full definition
{
  "$ref": "#/components/schemas/TablePublicMembershipCreatedDto"
}
Example response · 200 · application/json
{
  "membershipId": "4db41e65-a63b-4932-883c-e6c4306ce684",
  "tableSessionId": "9b456a94-f735-466f-84ba-67aa863b2905",
  "tableSessionGuestId": "cbca9476-6eef-441b-874e-918d61f54560",
  "revision": 1,
  "expiresAt": "2026-12-31T18:00:00.000Z",
  "capability": "synthetic-example-credentialxxxxxxxxxxxxxxx"
}
400The supplied identifier, query or credential shape is invalid.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 400 · application/json
{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}
401The QR credential, current native authority or exact requesting Origin is denied.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 401 · application/json
{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}
404The current public locator, presentation binding or owned native resource is unavailable.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}
409Idempotency conflict or documented operation-specific domain conflict
TablePublicCommandConflictDto
Full definition
{
  "$ref": "#/components/schemas/TablePublicCommandConflictDto"
}
Example response · 409 · application/json
{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "TABLE_PUBLIC_REVISION_CONFLICT",
  "message": "errors:http.conflict",
  "translationKey": "errors:http.conflict"
}
429The native join claim budget is exhausted.

Response headers

Retry-After

Whole seconds the client must wait before retrying the rejected request.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "example": 60
}
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 429 · application/json
{
  "statusCode": 429,
  "error": "errors:http.tooManyRequests",
  "code": "HTTP_TOO_MANY_REQUESTS",
  "message": "errors:http.tooManyRequests",
  "translationKey": "errors:http.tooManyRequests"
}
503QR key material or authoritative native state cannot be safely used.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 503 · application/json
{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Schemas

TablePublicMembershipCreatedDto

Original native membership grant with a private capability limited to its primary service session and operational guest slot. Validity remains subject to current epochs, revocation and presentation authority.

membershipIdRequired

Native table-session membership grant.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Native table-session membership grant.",
  "example": "4db41e65-a63b-4932-883c-e6c4306ce684"
}
tableSessionIdRequired

Primary native service session to which membership is limited.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Primary native service session to which membership is limited.",
  "example": "9b456a94-f735-466f-84ba-67aa863b2905"
}
tableSessionGuestIdRequired

Native operational guest slot assigned by the admission owner.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Native operational guest slot assigned by the admission owner.",
  "example": "cbca9476-6eef-441b-874e-918d61f54560"
}
revisionRequired

Membership authority revision.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "description": "Membership authority revision.",
  "example": 1
}
expiresAtRequired

Membership credential expiry instant.

string · date-time
Full definition
{
  "type": "string",
  "format": "date-time",
  "description": "Membership credential expiry instant.",
  "example": "2026-12-31T18:00:00.000Z"
}
capabilityRequired

Private session-scoped capability; store outside account transport and Redux state.

string
Full definition
{
  "type": "string",
  "minLength": 43,
  "maxLength": 43,
  "description": "Private session-scoped capability; store outside account transport and Redux state.",
  "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
}
Full definition
{
  "type": "object",
  "properties": {
    "membershipId": {
      "type": "string",
      "format": "uuid",
      "description": "Native table-session membership grant.",
      "example": "4db41e65-a63b-4932-883c-e6c4306ce684"
    },
    "tableSessionId": {
      "type": "string",
      "format": "uuid",
      "description": "Primary native service session to which membership is limited.",
      "example": "9b456a94-f735-466f-84ba-67aa863b2905"
    },
    "tableSessionGuestId": {
      "type": "string",
      "format": "uuid",
      "description": "Native operational guest slot assigned by the admission owner.",
      "example": "cbca9476-6eef-441b-874e-918d61f54560"
    },
    "revision": {
      "type": "integer",
      "minimum": 1,
      "description": "Membership authority revision.",
      "example": 1
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Membership credential expiry instant.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "capability": {
      "type": "string",
      "minLength": 43,
      "maxLength": 43,
      "description": "Private session-scoped capability; store outside account transport and Redux state.",
      "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
    }
  },
  "description": "Original native membership grant with a private capability limited to its primary service session and operational guest slot. Validity remains subject to current epochs, revocation and presentation authority.",
  "required": [
    "membershipId",
    "tableSessionId",
    "tableSessionGuestId",
    "revision",
    "expiresAt",
    "capability"
  ],
  "example": {
    "membershipId": "4db41e65-a63b-4932-883c-e6c4306ce684",
    "tableSessionId": "9b456a94-f735-466f-84ba-67aa863b2905",
    "tableSessionGuestId": "cbca9476-6eef-441b-874e-918d61f54560",
    "revision": 1,
    "expiresAt": "2026-12-31T18:00:00.000Z",
    "capability": "synthetic-example-credentialxxxxxxxxxxxxxxx"
  }
}
TranslatedErrorDto

Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.

statusCodeRequired

HTTP status code repeated from the response.

integer
Full definition
{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}
errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string
Full definition
{
  "type": "string",
  "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
  "example": "errors.request.invalid"
}
codeRequired

Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.

string
Full definition
{
  "type": "string",
  "example": "HTTP_BAD_REQUEST",
  "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
}
messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
}
translationKeyRequired

Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array
Full definition
{
  "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ValidationErrorDto"
  },
  "example": [
    {
      "field": "email",
      "translationKey": "validation:isEmail",
      "code": "isEmail",
      "message": "validation:isEmail"
    }
  ]
}
detailsOptional

Optional domain-specific blocker or validation details

oneOf
Full definition
{
  "description": "Optional domain-specific blocker or validation details",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "example": [
    "example"
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP status code repeated from the response.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Optional domain-specific blocker or validation details",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}
ValidationErrorDto

Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string
Full definition
{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}
translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
}
codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string
Full definition
{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}
messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Public field path. Nested properties and array indices are separated by dots."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}
JsonValue

Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.

Full definition
{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
  "example": "example"
}
TablePublicCommandConflictDto

Native QR command conflict caused by an in-flight or mismatched idempotency request, stale resource revision, changed join state, or unavailable native guest slot. Retry recovery retains the original command payload and authorization scope.

Full definition
{
  "description": "Native QR command conflict caused by an in-flight or mismatched idempotency request, stale resource revision, changed join state, or unavailable native guest slot. Retry recovery retains the original command payload and authorization scope.",
  "example": {
    "statusCode": 409,
    "error": "errors:http.conflict",
    "code": "TABLE_PUBLIC_REVISION_CONFLICT",
    "message": "errors:http.conflict",
    "translationKey": "errors:http.conflict"
  },
  "allOf": [
    {
      "$ref": "#/components/schemas/TranslatedErrorDto"
    },
    {
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "statusCode": {
          "type": "integer",
          "enum": [
            409
          ],
          "description": "HTTP 409 conflict status.",
          "example": 409
        },
        "code": {
          "type": "string",
          "enum": [
            "IDEMPOTENCY_REQUEST_NOT_READY",
            "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
            "IDEMPOTENCY_REQUEST_IN_PROGRESS",
            "IDEMPOTENCY_SCOPE_INCOMPLETE",
            "TABLE_PUBLIC_REVISION_CONFLICT",
            "TABLE_PUBLIC_JOIN_STATE_CONFLICT",
            "TABLE_PUBLIC_SLOT_UNAVAILABLE"
          ],
          "description": "Stable idempotency or operation-specific domain conflict code.",
          "example": "IDEMPOTENCY_REQUEST_NOT_READY"
        }
      },
      "example": {
        "code": "IDEMPOTENCY_REQUEST_NOT_READY"
      }
    }
  ]
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.