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