RefappRefapp

Connecting a customer account

View as Markdown

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>
PartValue
<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.
integrationKeyThe customer secret your system will send as X-Provider-Key. URL-encode it.
returnUrlThe 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.

refappStatusWhat happenedWhat to do
connectedThe 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_connectedThe 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.
cancelledThe administrator chose not to connect.Show the integration as not connected.
not_adminThe signed-in user may not change the account's integrations.Ask the customer to have a Refapp administrator do the connection.
errorAnother 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:

  • integrationKey or returnUrl is missing: Refapp shows a page-not-found error.
  • <system> is wrong, or returnUrl is 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.