AUT-1473 Document session-capped token TTLs in Authentication API

[dimitrystd]

@hhood-smartling Perhaps there is also something in the help center where we can add a similar note.

Explain that access/refresh token pairs are capped to a 12-hour session lifespan, so expiresIn/refreshExpiresIn shrink near the end of a session, and guide developers to re-authenticate rather than keep refreshing.

[hhood-smartling]

added info here - https://help.smartling.com/hc/en-us/articles/1260805176849-Authentication#:~:text=new%20access%20token-,Session%20lifespan,-Every%20access/refresh

[maescomua]

Wording review on the new session-lifetime docs. Left three inline suggestions:

1. Tag description — the current text contradicts itself ("regardless of how many times you refresh" vs. "never technically ran out of refreshes"); reworded to fix that and split a run-on sentence.
2. Refresh endpoint description — replaced the hyphen used as a dash with a colon (not the convention elsewhere in this file) and folded in the stray duplicate blank line above it.
3. refreshExpiresIn schema description — trimmed, since it was repeating the same explanation a third time on the same rendered page (tag → endpoint → schema).

All three also drop second-person phrasing ("you"/"your"/"don't") to keep a consistent, neutral register.

[maescomua]

Self-contradicts as written: "regardless of how many times you refresh" (time-based cap) vs. "even though you never technically ran out of refreshes" (implies a countable limit). Also drops second-person and splits a 47-word run-on sentence.

Suggested change

	Every access/refresh token pair is tied to a single underlying session,
	which has a fixed maximum lifespan of 12 hours, regardless of
	how many times you refresh. As a session approaches that limit,
	refreshing will return an access/refresh token pair capped to whatever
	time remains in the session rather than the usual TTLs, and if you keep
	refreshing right up to the end, requests will eventually fail with a
	401 even though you never technically ran out of refreshes. If you
	notice `refreshExpiresIn` shrinking across successive refresh calls,
	treat it as a sign the session is ending soon, and call
	`/auth-api/v2/authenticate` again with your `userIdentifier` and
	`userSecret` to start a new session.
	Every access/refresh token pair belongs to a single underlying session,
	which has a fixed maximum lifespan of 12 hours no matter how many times
	the pair is refreshed. As a session nears that limit, refreshing returns
	a token pair capped to whatever time is left in the session rather than
	the usual TTLs. Refreshing past that point eventually returns a 401,
	even though the refresh token itself hasn't expired. A shrinking
	`refreshExpiresIn` across successive refreshes is a sign the session is
	ending soon: call `/auth-api/v2/authenticate` again with the same
	`userIdentifier` and `userSecret` to start a new session.

[maescomua]

No other prose in this file uses a spaced hyphen as a dash (the one existing dash elsewhere is an em dash); restructured with a colon instead. Also drops "your"/"don't" and folds in the extra blank line above this paragraph.

Suggested change

	Refreshing does not reset your session - it only issues a new token
	pair within the current session's remaining lifetime, which is capped
	to 12 hours. As that session nears its maximum lifespan, the `expiresIn`
	and `refreshExpiresIn` values in the response will shrink to whatever
	time is left, and will eventually expire outright even though the
	refresh token hasn't been used up. If `refreshExpiresIn` keeps getting
	shorter across refreshes, don't just refresh faster - call
	`/auth-api/v2/authenticate` again to start a fresh session.
	Refreshing does not reset the session: it only issues a new token
	pair within the session's remaining lifetime, which is capped to
	12 hours. As the session nears that limit, `expiresIn` and
	`refreshExpiresIn` shrink to whatever time is left, and can
	eventually reach zero even though the refresh token hasn't expired.
	A shrinking `refreshExpiresIn` across repeated refreshes is a sign
	the session is ending: call `/auth-api/v2/authenticate` again to
	start a new session, rather than refreshing more often.

[maescomua]

This is the third near-verbatim copy of the same explanation, and it renders on the same page as the endpoint description right above it (this schema is shared by both the /authenticate and /authenticate/refresh responses). Trimmed to the essential mechanic, matching the pointer style already used in expiresIn's description.

Suggested change

	TTL (time-to-live) in seconds for the refresh token. Every
	access/refresh token pair belongs to an underlying session that has a
	fixed maximum lifespan of 12 hours, regardless of how many
	times you refresh. As a session nears that limit, this value is
	capped to whatever time is left in the session, so it will shrink on
	each successive refresh instead of resetting to its usual value, and
	can eventually reach zero even though the refresh token itself has
	not expired. Treat a shrinking `refreshExpiresIn` as a signal that
	the session is ending soon, and call `/auth-api/v2/authenticate`
	again with your `userIdentifier` and `userSecret` to start a new
	session, rather than continuing to refresh.
	TTL (time-to-live) in seconds for the refresh token. This value
	is tied to the token pair's underlying session, which has a
	fixed maximum lifespan of 12 hours regardless of how many times
	the pair is refreshed. As the session nears that limit,
	`refreshExpiresIn` shrinks toward zero rather than resetting to
	its usual value, even though the refresh token itself hasn't
	expired. A shrinking value is a signal to call
	`/auth-api/v2/authenticate` again and start a new session,
	rather than continue refreshing.