# Connect businesses

Work inside businesses that belong to other people: their approval, test businesses, the business header, a person's decision and how a connection ends.

## Bring a business

`POST /connected-businesses` names the business, its owner's address and the scopes you ask for. With `returnUrl` (one of your apps' registered addresses) the answer carries `approvalUrl`: send the owner there from your own screen. They sign in with their Praecise account, choose where the business lives (a new project, or one they already own), decide what you may do, and come back to your address with `connection` and `outcome`. Read the connection with your key; trust nothing else in the address.

Request:

```
curl -sS https://api.rivier.ai/connected-businesses \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbour Tours", "email": "owner@harbour.example", "scopes": ["bookings:admin", "bookings:decide", "contacts:write"], "ref": "host-42", "returnUrl": "https://you.example/back", "mail": false}'
```

## Test businesses

With a test key the same call makes a test business at once: connected, with every scope you asked for, no mail and no owner. A test key never reaches a live business and a live key never a test one. In a test business your test key also confirms and declines requests, since it has no people.

## Working inside a business

Every call with your secret key and the header `x-rivier-business` runs inside that business, held to what its owner granted. Your own records (connections, your customers) and the calls across businesses are refused with the header: call those from your own project. A business's events reach your stream as copies, each naming the connection as `business`, for the modules you were granted to read.

Request:

```
curl -sS https://api.rivier.ai/bookings/services \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "x-rivier-business: $CONNECTION_ID"
```

## A person's decision

Some acts are a person's, such as accepting a booking request. Ask for `bookings:decide`. Send the business's person to `/connect/act` on the app with the connection, its project and your return address; signed in, they come straight back with a `code`. Exchange it once, within five minutes, for a person token of 30 minutes, and send it as `x-rivier-person` on confirm and decline: the act is that person's.

Request:

```
curl -sS https://api.rivier.ai/connected-businesses/$CONNECTION_ID/person-tokens \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "$CODE"}'
```

## Pause, notices and the end

`/pause` refuses your calls and keeps the grant and the events; `/resume` brings them back. `notices` says who tells the people of a booking you make: you (the default) or the business. The owner can narrow your grant or end the connection at any time, and so can you. You hear `platform.business.connected`, `.declined`, `.expired`, `.granted`, `.paused`, `.resumed` and `.ended`.

## What Rivier guarantees, and what stays yours

Rivier holds you to your connection and its grant: one platform per business project, never the owner's keys, people or settings, and usage only to read. Every route is checked through each kind of credential on every release. What Rivier cannot know is which of your own users may act for which host or guest: check that in your own code before each call.

## Your own data

Declare the types your platform keeps (`POST /data/types`, or `rivier data push` from your code) and keep their rows in Rivier: by business, by customer, or for the whole project. A field may point at your own rows or at Rivier's services, bookings, products and contacts (`rivier_service` and the rest), checked where the row lives. Rows are reached on REST (`/data/:type`), in GraphQL as typed fields (`dataListing`, `dataListingList`), and by agents through `rivier_data_find` and the tools beside it. A customer token reaches only that customer's rows, and a call inside a business only that business's, down to the database's own row security.

## A share of each payment

Ask for a ceiling when you connect a business (`feeCeiling`, in basis points); its owner sees it before approving. A checkout you open inside the business may then carry `platformFee`, a fixed part and basis points that together stay under the ceiling. The business stays the merchant. The share is taken only through Skerry, and is switched on once Skerry takes a fee per payment.
