# How To / Onboard to Shopfront

# How-To: Onboard Customers into Shopfront

> [This is tightly related to authentication, we would highly suggest understanding how authentication works in Shopfront before continuing.](/documentation/General/Authentication)

## Getting Started

Shopfront provides applications with the ability to onboard customers directly onto Shopfront
with a free-trial which will automatically connect to your application once they've completed 
the sign-up form.

This is useful for redirecting users who don't already have a Shopfront account or for creating
new trial stores.

Your application and the user will go through the following flow:

1. Create connection token
2. Redirect user to sign-up page
3. User creates trial store
4. Shopfront connects and informs your application

## Creating the Onboarding Connection Token

The first step to onboarding a customer to automatically connect to your application is to
generate an onboarding connection token, this can be done by sending a `POST` request to
`https//onshopfront.com/api/onboard` with the following parameters (must be sent as `JSON`):

- `client_id`: The Client ID of your application
- `client_secret`: The Client Secret of your application
- `redirect_uri`: The redirect URI for your application
- `state`: The onboarding token's state (to verify the request from Shopfront)
- `scope`: The scopes requested, must be a string with each scope separated by a string
- `contact`: (optional) The contact details to pre-populate the sign-up form
- `contact.organisation_name`: (optional) The name of the organisation
- `contact.name`: (optional) The user's name 
- `contact.email`: (optional) The user's email
- `contact.phone`: (optional) The user's phone number

This will then respond with the following `JSON` body:

- `redirect_to`: The address to redirect the user to
- `token`: The ID of the token issued to your application, this can be used to verify the sign-up

**Creating the Onboarding Connection Token**

```javascript
const response = await fetch("https://onshopfront.com/api/onboard", {
    method : "POST",
    headers: {
        "Content-Type": "application/json",
        "Accept"      : "application/json",
    },
    body: JSON.stringify({
        client_id    : process.env.SHOPFRONT_CLIENT_ID,
        client_secret: process.env.SHOPFRONT_CLIENT_SECRET,
        redirect_uri : process.env.SHOPFRONT_REDIRECT_URI,
        state        : generateState(),
        scope        : "see_products see_cost",
        contact      : {
            organisation_name: "Test Organisation",
        },
    }),
});

if(response.status !== 200) {
    // We received an error response from Shopfront
    throw new Error("Unable to retrieve onboarding token from Shopfront");
}

const body = await response.json();

// Store the ID of the token for later if required
storeOnboardingToken(body.token);

// Perform the redirect to the sign-up form
redirectUser(body.redirect_to);
```

**Creating the Onboarding Connection Token**

```php
$ch = curl_init("https://onshopfront.com/api/onboard");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type" => "application/json",
    "Accept"       => "application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "client_id"     => env("SHOPFRONT_CLIENT_ID"),
    "client_secret" => env("SHOPFRONT_CLIENT_SECRET"),
    "redirect_uri"  => env("SHOPFRONT_REDIRECT_URI"),
    "state"         => generateState(),
    "scope"         => "see_products see_cost",
    "contact"       => [
        "organisation_name" => "Test Organisation",
    ],
]));

$response    = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if($status_code !== 200) {
    throw new Exception("Unable to retrieve onboarding token from Shopfront");
}

$body = json_decode($response);

// Store the ID of the token for later if required
storeOnboardingToken($body->token);

// Perform the redirect to the sign-up form
redirectUser($body->redirect_to);
```

## Receiving the Connection from Shopfront

After the user has successfully gone through the sign-up process, Shopfront will send a `GET` request
to your `redirect_uri` specified previously that includes all the details required to authorize
the user:

- `code`: A temporary code to retrieve an access token
- `state`: The state provided when requesting to onboarding token
- `vendor`: The subdomain of the store that was redirected
- `from_onboarding`: The ID of the token that was used to onboard the user

You can then exchange the provided `code` for an access token (like you would through the normal OAuth flow).

The response for this request will be ignored and the user will be left in Shopfront, so it's best to 
do things like send notifications to remind the user to complete the authorisation process if there are
further requirements by your application.