Skip to main content
POST
Create a borrower portal sign-in URL

Overview

Returns a single-use URL that opens the borrower portal already signed in, for a borrower your platform has already authenticated. Your backend requests the URL; you redirect the borrower to it. This exists so a borrower who has just signed in on your side is not asked to sign in a second time. No passwords, cookies or session tokens are shared between your platform and Finosu.
This feature is available only to explicitly approved integrations. Until it is enabled for your account, an authenticated request returns 403. Contact Finosu to have it enabled and to obtain your API key.

Flow

  1. A borrower signs in on your platform.
  2. Your backend calls this endpoint with your own identifier for that borrower.
  3. You redirect the borrower’s browser to the returned url.
  4. They land on the portal dashboard, signed in.
The call is server-to-server. Never make it from the browser: the response contains a credential that would then be visible to the borrower and to anything else running on the page.

The URL is a credential

The returned url is a short-lived bearer credential. Anyone holding it can exchange it once for that borrower’s session.
  • Do not write it to logs, analytics, error trackers, or support tickets.
  • Do not store it, email it, or include it in a redirect you record.
  • Redirect the borrower to it immediately and discard your copy.
It is single-use: the first redemption spends it, and every later attempt fails. It also expires shortly after issuance — see expiresIn. Responses are served with Cache-Control: no-store.

Expiry does not limit the session

expiresIn is how long the URL remains redeemable. Once redeemed, the borrower gets an ordinary portal session governed by the portal’s normal session policy, and that session is not cut short when the URL expires. Request a URL at the moment you are about to redirect, rather than issuing one ahead of time and holding it.

Identifying the borrower

externalCustomerId is your own identifier for the borrower, the same reference you send Finosu elsewhere. The lookup is scoped to the company your API key authenticates as, so a reference belonging to another company returns 404. externalLoanId is optional. A borrower’s loans at one company share a single portal account, so naming a loan does not change what the session can reach. Send it when a borrower’s loans span more than one of your brands, so the link opens the right branded portal. If the loan reference does not identify a live loan belonging to that borrower — whether it names another borrower’s loan, a loan that has been removed, or a reference we have never seen — the request is rejected with 409 and no URL is issued. That check exists to catch a mis-keyed mapping before it hands a borrower someone else’s account, so treat a 409 as a data problem on your side rather than something to retry.

Example

Redirect the borrower to url. Nothing else in the response needs to be stored.

Errors

A 404 and a 409 are different failures. 404 means no borrower matches that reference within the company your key authenticates as — a borrower belonging to another company is not visible to your key. 409 means the borrower was found, but the loan reference does not resolve to a live loan of theirs.

Redemption failures

If the borrower opens a URL that has already been used, has expired, or was never issued, the portal shows one neutral message asking them to return to your platform and open a new link. Those three cases are deliberately indistinguishable, so a URL cannot be probed to learn whether it ever existed. If a borrower reports that a link did not work, issue a new one rather than asking them to retry the old one — a spent URL can never work again.

Authorizations

X-API-Key
string
header
required

Body

application/json
externalCustomerId
string
required

Your identifier for the borrower, as sent to Finosu.

Required string length: 1 - 255
externalLoanId
string | null

Optional. A borrower's loans at one company share a single portal account, so this does not change what the session can reach. Send it when a borrower's loans span more than one of your brands, so the link opens the right branded portal. If it does not identify a live loan belonging to that borrower — another borrower's loan, a removed loan, or an unknown reference — the request is rejected with 409.

Required string length: 1 - 255

Response

Single-use sign-in URL. Served with Cache-Control: no-store.

url
string
required

Single-use sign-in URL. Treat as a secret; redirect the borrower to it.

expiresAt
string<date-time>
required

Absolute time the URL stops working.

expiresIn
integer
required

Seconds until the URL stops working. The borrower's session is not limited by this value.