> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v80/llms.txt)

# Start Public Link Session

> POST /public_link_sessions
> 
> Exchanges a public link's share token, and its password when the link has one, for a short-lived session token. No user, API app or access token is involved; this is the call an anonymous visitor's client (or a BFF acting for it) makes.
> 
> ### Session token
> 
> - Expires after `expires_in` seconds (3600). Request a new one when it lapses.
> - Works **only** on `GET /public_link_sessions/current/feed` and `POST /public_link_sessions/current/pages/{page_id}/records`. Every other route answers `401`: it is not an access token, names no user and carries no role.
> - Bound to the link. Disabling, deleting or expiring the link, or switching public links off, ends every session for it at once.
> 
> ### Share token
> 
> `share_token` is the `share_token` query value of the link's `public_url`, unchanged. The `publicLinkLegacyShareTokens` server setting can turn this format off.
> 
> ### Limits
> 
> Wrong passwords are counted per link: 20 in 15 minutes, then `429`. The `publicLinkSessionLimits` server setting overrides this.
> 
> Per-client-IP limits on session requests (`sessions_per_ip_per_minute`), share tokens that open no link (`invalid_tokens_per_ip`, every `404`) and wrong passwords (`password_failures_per_ip`) are **off by default**. When the portal's backend makes the calls, every visitor shares its address, so it must rate-limit per visitor itself. Switch them on through `publicLinkSessionLimits` only where browsers call the API directly; the client IP is then the address the load balancer saw.



## Servers
- https://api.iformbuilder.com/exzact/api/v80/[servername]: https://api.iformbuilder.com/exzact/api/v80/[servername]



## Parameters



### Body: application/json (object)

- **share_token** (string)
  the `share_token` value from the link's `public_url`

- **password** (string)
  the link's password, in plain text; required when the link has one

- **page_id** (integer)
  optional; when sent it must be the link's page, as in the `public_url` path



## Responses
### 200
OK - the session was issued.

#### Body: application/json (object)
- **access_token** (string)
  the session token, sent as `Authorization: Bearer {access_token}` on the `/public_link_sessions/current/...` routes only

- **token_type** (string)

- **expires_in** (integer)
  seconds until the session expires

- **profile_id** (integer)
  the link's profile

- **page_id** (integer)
  the link's page


### 400
Bad Request - the body is not a JSON object, `share_token` is missing, or `password` / `page_id` has the wrong type.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 401
Unauthorized - the link has a password and it is missing (`Password required`) or wrong (`Incorrect password`).

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 403
Forbidden - public links are switched off on the server (`publicLinkEnabled` is not 1) or not activated (no `PUBLICLINKAPI` API app).

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 404
Not Found - the share token is malformed or unknown, the link is disabled, before its `activation_date` or at or after its `expiration_date`, `page_id` is not the link's page, or base64 share tokens are switched off. Every one of these answers the same way.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 429
Too Many Requests - too many wrong passwords for this link, or, when the per-IP limits are switched on, too many session requests, share tokens that opened no link, or wrong passwords from this client IP. Retry after the window.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure



[Powered by Bump.sh](https://bump.sh)
