# 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](generic-ats-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

```text
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

```mermaid
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:

- `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.
