Connecting a customer account
A customer can connect their Refapp account to your system themselves, without copying the customer secret into Refapp by hand. Your system sends a customer administrator to a Refapp page in the browser. The administrator confirms, and Refapp sends them back to your system with the outcome.
#Before you start
Ask your Refapp partnership contact to register the hosts of the pages you want customers to return to, in each environment you use. Refapp only sends users back to hosts registered for your integration. These are the same hosts that receive your status updates, so a host you already use for status updates works as it is.
Until a host is registered, the page tells the administrator that your system can't be connected from it, and does not send them back.
#The onboarding URL
https://<refapp host>/onboard/ats/<system>?integrationKey=<customer secret>&returnUrl=<your page>| Part | Value |
|---|---|
<refapp host> | The Refapp instance the customer uses, such as app.refapp.se or test.refapp.se. Refapp does not forward between instances, so your system has to know which one the customer is on. |
<system> | The system name Refapp gave your integration, genericAts in the test environment. |
integrationKey | The customer secret your system will send as X-Provider-Key. URL-encode it. |
returnUrl | The page in your system to come back to, over https, on a registered host. URL-encode it. |
Generate a new, random secret for each customer. Refapp refuses a secret that another Refapp account already holds.
#Flow
sequenceDiagram
participant Admin as Customer administrator
participant ATS as Your system
participant Refapp
Admin->>ATS: Chooses to connect Refapp
ATS->>Admin: Redirect to /onboard/ats/<system>?integrationKey=…&returnUrl=…
Admin->>Refapp: Opens the onboarding page
opt Not signed in
Refapp->>Admin: Sign-in
Admin->>Refapp: Signs in, back on the onboarding page
end
Refapp-->>Admin: Shows the Refapp account the secret will be added to
Admin->>Refapp: Connect or Cancel
Refapp->>Admin: Redirect to returnUrl?refappStatus=…
Admin->>ATS: Opens returnUrl
ATS->>Refapp: GET /webhooks/ats-generic/config with the secret
Refapp-->>ATS: 200 when the connection works
The secret goes to the account the administrator is signed in to. If they belong to several accounts, the confirm screen names the account so they can check it before connecting.
#Handling the result
Refapp sends the administrator back to returnUrl with one added search
parameter, refappStatus. Any search parameters already in returnUrl are
kept.
refappStatus | What happened | What to do |
|---|---|---|
connected | The secret was added to the account. | Call GET /webhooks/ats-generic/config with the secret to confirm the connection, then show the integration as connected. |
already_connected | The account already has a secret for your system. Nothing changed. | Your secret was not saved. If your system does not know the secret the account has, ask the customer to contact Refapp support. |
cancelled | The administrator chose not to connect. | Show the integration as not connected. |
not_admin | The signed-in user may not change the account's integrations. | Ask the customer to have a Refapp administrator do the connection. |
error | Another Refapp account already holds this secret. Nothing changed. | Generate a new secret and let the administrator try again. |
Treat refappStatus as a hint for what to show the user, not as proof:
anyone can open returnUrl with any status. Only a successful call to the
configuration endpoint with the secret shows that the connection works.
The administrator is not sent back in these cases, so check them in the test environment before going live:
integrationKeyorreturnUrlis missing: Refapp shows a page-not-found error.<system>is wrong, orreturnUrlis not https on a registered host: Refapp shows an error and no way back, because it will not redirect to an address it can't trust.
#Security
The customer secret travels in the browser URL, both to Refapp and, if you
include it, in returnUrl. It can therefore end up in browser history and in
proxy and access logs. Keep this in mind when you choose how to handle it:
- Use one secret per customer, so a leaked secret affects one account only.
- Don't put the secret in
returnUrl. Identify the customer in your own session instead. - If a secret may have leaked, contact Refapp support to replace it.
Refapp never overwrites a secret an account already has, never adds a secret another account holds, and never names the other account when it refuses.