# Connecting to shared accounts

> This page is for the third party: an organisation that a Shuttle platform has given an OAuth client, to work with that platform's merchants' accounts. If you ar

This page is for the third party: an organisation that a Shuttle platform has given an OAuth client, to work with that platform's merchants' accounts. If you are the platform sharing its merchants, start with [Account sharing](/platforms/account-sharing/overview/).

You will have been given a **client ID** and a **client secret**, one pair for sandbox and one for live. Ask the merchant which environment they want to connect, and use that pair throughout.

Shuttle uses the OAuth 2.0 Authorization Code flow:

1. Send the merchant to Shuttle to grant access.
2. Shuttle sends them back to you with an authorisation code.
3. Exchange the code for an access token and a refresh token.
4. [Call the API](/platforms/account-sharing/access-tokens/) with the access token, and refresh it when it expires.

## 1. Send the merchant to Shuttle

Redirect the merchant to the authorisation endpoint:

```
https://merchant.shuttleglobal.com/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_url=https://yourapp.example/callback
  &state=RANDOM_VALUE
```

| Parameter | |
| --- | --- |
| `response_type` | Always `code` |
| `client_id` | Your client ID |
| `redirect_url` | Where to send the merchant afterwards |
| `scope` | Optional: space-separated scopes |
| `state` | A random value you check when the merchant comes back, to protect against cross-site request forgery; you can also use it to remember who started the flow |

The merchant then:

1. Logs into the Merchant Portal, or creates a login
2. Chooses an organisation, if they have more than one
3. Chooses one of the accounts they have connected from the platform that gave you the client (accounts from other platforms aren't offered)
4. Clicks **Grant Access**

## 2. Handle the redirect

Shuttle sends the merchant back to your `redirect_url` with a code:

```
https://yourapp.example/callback?code=AUTH_CODE&state=RANDOM_VALUE
```

Check that `state` matches what you sent.

Exchange the code within 15 minutes.

## 3. Exchange the code for tokens

```http
POST https://merchant.shuttleglobal.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.example/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
```

`redirect_uri` must be the same URL you sent as `redirect_url` in step 1. You can send the client ID and secret as HTTP Basic credentials (`Authorization: Basic base64(client_id:client_secret)`) instead of in the body. Use one or the other, not both.

```json
{
  "token_type": "Bearer",
  "access_token": "at_1234_h480djs93hd8",
  "refresh_token": "rt_1234_8xLOxBtZp8",
  "expires_in": 3600
}
```

Store both tokens against the merchant's account in your system, encrypted. Each pair works for that one account only.

## 4. Refresh the access token

Access tokens expire after an hour (`expires_in`, in seconds). Get a new one with the refresh token:

```http
POST https://merchant.shuttleglobal.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_1234_8xLOxBtZp8
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
```

The response has a new `access_token` and the same `refresh_token`. If refreshing fails, it usually means the merchant's access has been removed (see [Removing access](/platforms/account-sharing/removing-access/)): ask them to connect again.

The endpoints are in the API reference: [Authorize](/platforms/reference/oauth/operations/authorize/), [Get a token](/platforms/reference/oauth/operations/gettoken/), [Revoke a token](/platforms/reference/oauth/operations/revoketoken/), [Introspect a token](/platforms/reference/oauth/operations/introspecttoken/) and [Who am I](/platforms/reference/oauth/operations/getclientidentity/).