Introduction

A hosted session is a Bardge-hosted web experience that you open inside your own app for an already-provisioned member — letting them view their pass, discover providers, and generate a check-in code without you building any of that UI yourself. It is not an SDK: your backend creates the session, and your app opens the returned link in a webview. Create a session for a member only after a pass has been (or should be) issued for them through the Passes API.

Demo video — watch a hosted session end to end, from the member opening the link to checking in at a provider.

What you can do

Create a hosted session for a client

Key concepts

Creating a session

POST /hosted_sessions

Authenticates the same way as every other endpoint in this API — see Authentication. Request body:

{"client_id": "your-client-id"}

Response — active pass

{
  "object": "hosted_session",
  "url": "https://bardge-webview.vercel.app/<session-token>",
  "message": "SUCCESS"
}

Open url inside a webview in your app. It's opaque and contains no raw client or reseller identifiers.

This plain shape — no status, no resolution — is what you get for a client whose pass is currently active. If the client's pass isn't usable, the same call still returns a valid url, plus fields that tell you what's wrong and how to fix it.

When the pass isn't usable — resolution steps included

The session is always created, so url is always valid and safe to open. But when the client's pass isn't currently usable, the response carries three extra fields — status, is_error, and resolution — so you can fix the problem from your backend without waiting for the member to open the webview and report a dead end.

`status`	What it means	`resolution.action`
`no_entitlement`	No pass has ever been assigned to this client, or their only pass is unusable (e.g. cancelled)	`issue_pass`
`pass_expired`	The client has a pass, but it has lapsed past its expiry date	`renew_pass`

is_error is always false on both — neither is a failure, and the call is still a 200.

no_entitlement — no pass to render

If no pass has ever been assigned to the client, or their only pass sits in some other unusable state, the response surfaces the fix directly:

{
  "object": "hosted_session",
  "url": "https://bardge-webview.vercel.app/xO9IT8bnVasaN2P2NBbLrIz0i05p4O48",
  "message": "SUCCESS",
  "status": "no_entitlement",
  "is_error": false,
  "resolution": {
    "action": "issue_pass",
    "required_fields": ["pass_id", "client_id"],
    "next_step": "After issuing, reopen the session URL for this member."
  },
  "member": {"client_id": "bardge9370"},
  "businessName": "Meridian Health"
}

resolution tells you exactly what to do: issue a pass for this member using the listed fields (see Passes), then reopen the session URL for them. businessName is your business name as the member sees it, for copy like "Reach out to {businessName}".

pass_expired — pass has lapsed

If the client's most recent pass has run past its expiry date, the response says so and points at renewal rather than issuance — the member already has a pass record, so you don't need to (and shouldn't) issue a new one:

{
  "object": "hosted_session",
  "url": "https://bardge-webview.vercel.app/xO9IT8bnVasaN2P2NBbLrIz0i05p4O48",
  "message": "SUCCESS",
  "status": "pass_expired",
  "is_error": false,
  "resolution": {
    "action": "renew_pass",
    "required_fields": ["client_id"],
    "next_step": "Renew this member's pass — POST /issued_passes/{client_id}/renew for a prepaid pass, or POST /issued_passes/{client_id}/expiry for a pay-as-you-go pass — then reopen the session URL for this member."
  },
  "member": {"client_id": "bardge9370"},
  "businessName": "Meridian Health"
}

Which renewal call applies depends on the pass's payment model:

Prepaid pass — POST /issued_passes/{client_id}/renew extends the pass by one billing cycle at its current price.

Pay-as-you-go pass — POST /issued_passes/{client_id}/expiry sets a new expiry date.

Calling the wrong one returns 403 permission_denied telling you to use the other, so it's safe to attempt one and fall through. If you don't know which model your clients are on, reach out to your business relationship manager. Either way, reopen the session URL for the member once the pass is back in force.

If the member opens the session before you renew, they see an "expired pass" state in the webview rather than an error — so this response is a heads-up, not something you must act on before handing over the url.

Accepts an Idempotency-Key header — see Idempotent Requests. Retrying the same request with the same key returns the original session URL instead of minting a new one.

Session validity

A session link is valid for a limited window from creation and may be opened more than once within it. Once opened, the session is managed entirely by Bardge — no further action is required on your end.

Errors

{
  "error": {
    "type": "authentication_error",
    "code": "session_expired",
    "message": "Session link is invalid or has expired",
    "request_id": "req_..."
  }
}

Status	code	When
401	`authentication_required`	Invalid API key (create-session call)
403	`permission_denied`	Reseller account is not enabled (create-session call)
404	`not_found`	The `client_id` isn't recognized for this reseller (create-session call)
400	`invalid_request`	A required field is missing or invalid
401	`session_expired`	The session token is unrecognized or past its validity window (resolve call)
409	`idempotency_conflict`	Same `Idempotency-Key`, different request body (create-session call)

Passes — issue a pass before creating a session for a client who doesn't have one, or renew one that has expired

Authentication — how the create-session call authenticates

Idempotent Requests — safely retry a create-session call

Providers — the hosted session lets members discover providers covered by their pass

Access Codes — the hosted session lets members generate a check-in code for their visit

What you can do#

Key concepts#

Related sections#

What you can do

Key concepts

Related sections