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_inseconds (3600). Request a new one when it lapses. - Works only on
GET /public_link_sessions/current/feedandPOST /public_link_sessions/current/pages/{page_id}/records. Every other route answers401: 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.
Responses
-
OK - the session was issued.
-
Bad Request - the body is not a JSON object,
share_tokenis missing, orpassword/page_idhas the wrong type. -
Unauthorized - the link has a password and it is missing (
Password required) or wrong (Incorrect password). -
Forbidden - public links are switched off on the server (
publicLinkEnabledis not 1) or not activated (noPUBLICLINKAPIAPI app). -
Not Found - the share token is malformed or unknown, the link is disabled, before its
activation_dateor at or after itsexpiration_date,page_idis not the link's page, or base64 share tokens are switched off. Every one of these answers the same way. -
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.
curl \
--request POST 'https://api.iformbuilder.com/exzact/api/v81/[servername]/public_link_sessions' \
--header "Content-Type: application/json" \
--data '{
"share_token": "MDEyMzQ1Njc4OWFiY2RlZi40Mg==",
"password": "********"
}'
{
"share_token": "MDEyMzQ1Njc4OWFiY2RlZi40Mg==",
"password": "********"
}
{
"access_token": "pls_0123456789abcdef0123456789abcdef.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"token_type": "Bearer",
"expires_in": 3600,
"profile_id": 67890,
"page_id": 123456
}
{
"error_message": "string"
}
{
"error_message": "string"
}
{
"error_message": "string"
}
{
"error_message": "string"
}
{
"error_message": "string"
}