Private apps
A private app is the integration of one organization: a merchant's own ERP, warehouse system or script, or an agency's integration built for a client. It is made in the partner portal like any app and calls the same API with the same scopes, but:
- it belongs to one organization, chosen when it is created, and installs nowhere else;
- it is never in the app store and has no store listing;
- it is never reviewed: its partner publishes each version directly;
- it has no redirect URI: an administrator of the organization approves it once, through its install link, and from then on the app takes its own tokens with OAuth client credentials (its client ID and secret). Your system needs no public HTTPS address for that.
Software many merchants install is a public app instead: your app and OAuth. Not sure which you need: choose your path.
1. Create it
Section titled "1. Create it"-
Sign in to the partner portal (the partner account; a merchant uses the same sign-in account as in the dashboard).
-
In Apps, press New app and pick the kind Private. The kind is fixed: a private app never becomes public, nor the other way round.
-
Give it a name. Reserved names (the platform's, its assistant's, a vendor's from the integration catalog) are refused as for any app; another app may hold the same name.
-
Pick the organization it belongs to:
- One of the account's organizations: a list of the organizations your account is a member of, test organizations marked;
- A client's organization: its Organization ID (
org_...), which anyone in that organization copies from Settings → Organization → General in the dashboard and sends you.
-
Create it. The
client_idandclient_secretare shown at once; the secret only once, so copy it then.
The organization cannot be changed afterwards: an integration for another organization is another private app.
2. Pick its scopes and publish
Section titled "2. Pick its scopes and publish"On the app's Details tab, pick the scopes the app needs and, for an app working as one of the organization's integrations, what it provides (a store sending its orders: store apps). Save.
Changes are saved to the version being worked on. Publish, in the bar above the tabs, makes it the published version at once, with no review; it needs a name and at least one scope. Until its first publication the app cannot be installed.
3. The install link
Section titled "3. The install link"On the Installations tab, copy the install link and send it to an administrator of the organization (yourself, for your own organization). It has this shape:
https://connectato.com/app/install/app_...The link names no organization. Opened by a member of the app's organization, it leads to the app's approval page there, in the dashboard; anyone else gets 404. The page lists the permissions the published version asks for and what the app adds to the organization. Approving needs, in that organization:
- the permission to manage the organization's connected apps (the owner always has it);
- the permission behind each scope (the ceiling);
- for an app that provides an integration, that integration's permission (managing integrations, for a store).
A person missing one sees why, and cannot approve. Once approved, the app shows in Applications → My applications, with its permissions, its calls and Uninstall; the Installations tab in the portal shows the installation.
4. Tokens: client credentials
Section titled "4. Tokens: client credentials"Your server asks for a token with the app's own credentials, at the main host's token endpoint (the same one public apps use):
curl -X POST "https://connectato.com/oauth/token" \ -d grant_type=client_credentials \ -d client_id="$CLIENT_ID" \ -d client_secret="$CLIENT_SECRET"<?php
use GuzzleHttp\Client;
$response = (new Client())->post('https://connectato.com/oauth/token', [ 'form_params' => [ 'grant_type' => 'client_credentials', 'client_id' => getenv('CLIENT_ID'), 'client_secret' => getenv('CLIENT_SECRET'), ],]);
$token = json_decode((string) $response->getBody(), true);const response = await fetch('https://connectato.com/oauth/token', { method: 'POST', body: new URLSearchParams({ grant_type: 'client_credentials', client_id: process.env.CLIENT_ID, client_secret: process.env.CLIENT_SECRET, }),});
const token = await response.json();import os
import requests
response = requests.post( "https://connectato.com/oauth/token", data={ "grant_type": "client_credentials", "client_id": os.environ["CLIENT_ID"], "client_secret": os.environ["CLIENT_SECRET"], },)
token = response.json()The answer:
{ "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."}- The token lives 60 minutes (
expires_in, in seconds). There is no refresh token: when it expires, ask for a new one the same way. - The token stands for the app's installation in its organization. Asked without
scope, it carries every scope the installation was granted. Withscope(space separated,scope=read_orders read_shipments) it is narrowed to those; a scope the installation lacks is never added.caller.scopesonGET /organizationshows what the token may use. - A token can be issued before the app is installed, but every call with it gets a
401until the installation is approved. After an uninstall, or while the app is suspended, its tokens get a401too. - A wrong secret is refused with
invalid_client. Only a private app may use this grant: a public app's client getsunauthorized_client.
5. Call the API
Section titled "5. Call the API"The token goes in the Authorization header as a Bearer token: Authorization: Bearer <access_token>. Start with GET https://api.connectato.com/v1/organization (first call): id is the organization, caller.scopes what the token may use, caller.app_id the app's client_id.
Every call is recorded: the organization sees it on the app's page in My applications, you on the Calls tab. The rate limit is the installation's.
Webhooks
Section titled "Webhooks"A private app receives webhooks like any app: the URL and events on the Webhooks tab, each event only when the installation's scopes can read it. Only the webhook URL needs to be reachable: https, http only for localhost while you develop. Without webhooks, follow what changes with updated_since.
New versions
Section titled "New versions"A change on Details opens the next version; the organization keeps using the published one until you press Publish again.
- A version asking for fewer scopes narrows the installation as soon as it is published.
- A version asking for more scopes changes nothing until the organization approves them: the app shows "New permissions to approve" in My applications, and Approve new permissions opens the same install link, which then lists only what is new. Send the link again to the administrator. Until then, a call needing a new scope gets a
403(insufficient_scope).
Uninstalling and ending it
Section titled "Uninstalling and ending it"- The organization uninstalls the app from My applications, with Uninstall. Its tokens are refused at once, and the app receives
app.uninstalledif it receives webhooks. The same install link installs it again. - Deleting, retiring and suspension work as for any app (your app).
- If its organization is deleted, the app stays in the portal, marked so, and can no longer be installed anywhere.