Referral Link
A Referral Link is a one-time URL returned by RefX APIs. They allow users of external systems to authenticate with RefX to perform scoped actions on specific referrals in their browser. You will see these links in responses such as Create link upsert and in the url field or links array returned by Get full details for a referral.
What happens when a link is opened
When a user opens a Referral Link, RefX exchanges that link for a session using the auth token tied to it. The auth token is immediately consumed and cannot be reused, and the user is redirected automatically to the page where they can take their action. The user’s browser continues to allow access to the referral until the session expires.
Expiry, one-time usage, and scope
Referral Links are single-use. The first successful visit consumes the link, and subsequent visits with the same URL will fail.
Referral Links are short-lived and may expire even if they were never used. Treat them as time-bound and reissue as needed. The expiry time of a link is 15 minutes from the time it is created.
If a user clicks on a Referral Link after it has been consumed or expired, they will see an error page indicating that the link is no longer valid.
The sessions generated by Referral Links are scoped to specific referrals and actions. They cannot be used to access other referrals or perform actions outside their intended scope.
The session persists on the user’s browser after the link is consumed, so users can continue in the same browser without needing the link again as long as they are performing the same action on the same referral.
Requester identifier
When fetching a Referral Link, include a requester identifier for audit purposes. It can be any identifier for the individual user requesting the link (for example, an email address or a UUID), as long as it uniquely maps to a user in your system.
APIs that require a requester identifier when retrieving a Referral Link:
Create link upsert(POST /links/upsert)Get full details for a referral(GET /referrals/:referralId) when requestingadditionalField=linkoradditionalField=url
Implementation guide
The recommended way to implement Referral Links is to generate them just-in-time when the user is about to take an action, rather than pre-generating and storing them for later use. This minimizes the chance of expiry or reuse issues occurring.
For example, for referral upsert, the button that the user clicks to upsert a referral should trigger a call to the Create link upsert API to fetch a fresh link, which is then opened in the browser.
For action links returned in the Get full details for a referral API, the links can be fetched when the referral is first displayed to show the actions available to the user. But when the user clicks on an action, the link should be regenerated by calling the Get full details for a referral API again and using the new link returned instead of the original link fetched earlier. The same would apply for the link returned in the url field.
