# Which key do I need? > The platform client and the organisation key open different doors. How to tell which one you need for which call, and which capabilities control what. The platform client and the organisation key are both a `client_id` and a `client_secret` that you exchange for a token, and that is what confuses. They are two different things. They fetch tokens at different addresses and in a different form, they reach partly different APIs, and what you may do is decided in different ways. This guide shows which one you need for which call, before you write a line of code. - Market: Sweden (`se`). Norway differs in currency, payment methods and what happens when nobody pays: https://developers.rivr.io/guides/which-key.md?market=no - Language: English (`en`). Svenska: https://developers.rivr.io/guides/which-key.md?lang=sv - 5 min read · 5 steps - Page in the portal: https://developers.rivr.io/guides/which-key Every example targets the sandbox (`https://api.test.rivr.io`) and needs test credentials. A platform client's tokens come from `https://auth.test.rivr.io`, an organisation key's from `https://auth.test.rivr.tech`. ## 1. Two credentials that look alike *Rivr → Journal system* The difference is who creates them, where the token is fetched and what the token is good for. **The platform client** is created by Rivr for your platform, that is a journal system with many clinics. You fetch a platform token and then a merchant token per clinic, with a JSON body from `auth.test.rivr.io`. It is for `/api/public`. The clinic lives in the token, and what the token may do is decided by the client's scopes (`public:*`). **The organisation key** is created by an admin in your own organisation, on the API keys page, who chooses which capabilities that key gets. You fetch a token form-encoded from `auth.test.rivr.tech`, and `resource` is required. It is for the routes in `/api/public` that a key reaches. One token covers every clinic the key reaches, and you name the clinic on each call in the `Rivr-Organization` header. **Why:** A platform is one journal system with many clinics, so the clinic is chosen when you fetch the token and becomes a boundary in it. An organisation reaches the clinics that belong to it, so the key has one token for everything it reaches and the clinic is chosen per call. **What your system does:** Find out which one you have. The `client_id` and `client_secret` that Rivr handed over for your platform are the platform client. A key that an admin created on the API keys page is an organisation key. If you have both, keep them apart. > **Warning.** Don't mix up the token requests. The platform's goes as JSON to `auth.test.rivr.io`. The key's goes form-encoded to `auth.test.rivr.tech`, and there `resource` is required. ## 2. Which call needs which? *Journal system → Rivr* **Only the platform client:** the list of clinics (`GET /api/public/merchants`) and onboarding new clinics. Those routes are closed to keys and answer `403` with `route_not_available`. The account connection (`/oauth/authorize`, `/oauth/token` and `/oauth/deauthorize`, the guide Connect a clinic that already has a Rivr account) also works with the platform client only, and its code exchange is form-encoded to `auth.test.rivr.io` (the sandbox first, production when Rivr confirms). **Either works:** creating, reading, refunding and cancelling orders for a clinic, sending an order to a device, and reading settlements, devices and subscriptions. These are the routes in `/api/public` that a key reaches. With the platform client the client's scopes decide what you may do, and with a key its capabilities do. **What your system does:** If you connect new clinics for many, or need the list of them: use the platform client. If you read orders for your own organisation, or a clinic calls for itself: use a key. They don't replace each other. ## 3. The capabilities: what each tick opens *Rivr* An organisation key has only the capabilities someone has ticked for that very key, and they can be changed afterwards. For `/api/public` Rivr turns the key's capabilities on the clinic into `public:*` scopes in a short clinic token, and that is what reaches `/api/public`. This is how they fit together. `orders:read` alone gives `public:orders:status`, that is the order's id and status without personal data. `orders:read` together with `customers:read` gives `public:orders:read`, the whole order with the patient, and `public:subscriptions:read`. `orders:manage` together with `customers:read` gives `public:orders:write` (create, refund, cancel, send to a device) and `public:subscriptions:write`. `orders:manage` without `customers:read` opens no write routes. `economy:read` gives `public:order-settlements:read`, and `settings:read` gives `public:devices:read` and `public:merchants:read` for the clinic's own details. `events:read` gives nothing in `/api/public`, so a key that has only that gets `403` with `organization_not_accessible` there. **Why:** An order answer carries the patient's personal number, name and address in clear text. That is why `orders:read` is not enough to read a whole order, and why the write routes need `customers:read` too: they answer with the whole order. **What your system does:** Tick the least that is enough. When you change the capabilities on the API keys page, the change applies within about a minute, with the same key and also to tokens already issued. **In the portal:** [Choose capabilities on the API keys page](https://developers.rivr.io/keys) ## 4. Patient data: ask for customers:read only when you need the patient *Rivr* Patient data sits behind `customers:read`, which Rivr classes as health data. In `/api/public`, `public:orders:read` returns the whole order with the personal number in clear text. A key gets that scope when it has `orders:read` and `customers:read` together, and with the platform client it is the client's own scope that lets it through. A key that only needs to confirm an order is paid needs `orders:read` and nothing more. Then it never reaches any patient data. **Why:** An integration that doesn't need the patient should never get one. > **Note.** What is echoed in webhooks, what you must not put in `reference` and `metadata`, and how a protected identity is shown are in the guide Patient data in your calls and webhooks. **In the portal:** [The Patient data guide](https://developers.rivr.io/guides/patient-data) ## 5. Read the error: it points out which key is wrong *Rivr → Journal system* A wrong key usually gets an error that says what is missing. The error code in the answer tells you what to do. `merchant_token_required` (`401`): a clinic call was made with a platform token. Fetch a merchant token for the clinic. `platform_token_required` (`401`): a call about the platform, onboarding for example, was made with a clinic token. Fetch a platform token. `route_not_available` (`403`): a key called a route that is closed to keys. Make the call with the platform client. `invalid_scope` (`403`): the token lacks the scope the route needs. A platform client asks Rivr to add the scope. A key gets it when you tick the capability that gives it. `organization_required` (`400`) and `organization_not_accessible` (`403`): the call doesn't say which clinic it is about, or the key doesn't reach the clinic. Send `Rivr-Organization` with the clinic's id. **In the portal:** [All error codes](https://developers.rivr.io/errors) ## Common pitfalls - Fetching the platform token form-encoded, or the key's token as JSON. The platform's goes as JSON to `auth.test.rivr.io`. The key's goes form-encoded to `auth.test.rivr.tech` and requires `resource`. - Ticking `orders:manage` without `customers:read` and expecting to create orders. The key gets only `public:health:read`, and the write call answers `403` with `invalid_scope`. - Giving a key `customers:read` so that it can confirm payment. `orders:read` is enough, and with `customers:read` the key can read patient data. - Leaving out `Rivr-Organization` when the key reaches several clinics. The answer is `400` with `organization_required`. The header can be left out only when the key reaches exactly one clinic. ## Next guide - [Call /api/public with a key](https://developers.rivr.io/guides/org-keys-api-public.md): An organisation key for a clinic's orders, settlements, subscriptions and devices: which clinic the call is about, which routes the key reaches and what the refusals mean. - [Connect as a platform](https://developers.rivr.io/guides/connect.md): One set of credentials for the whole journal system, one token per clinic. - [Patient data in your calls and webhooks](https://developers.rivr.io/guides/patient-data.md): Where patient data lives in a Rivr integration, what comes back and what doesn't — and the one rule that saves you the most trouble.