Skip to content

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. Sign in to the partner portal (the partner account; a merchant uses the same sign-in account as in the dashboard).

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

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

  4. 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.
  5. Create it. The client_id and client_secret are 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.

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.

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.

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):

Terminal window
curl -X POST "https://connectato.com/oauth/token" \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET"

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. With scope (space separated, scope=read_orders read_shipments) it is narrowed to those; a scope the installation lacks is never added. caller.scopes on GET /organization shows what the token may use.
  • A token can be issued before the app is installed, but every call with it gets a 401 until the installation is approved. After an uninstall, or while the app is suspended, its tokens get a 401 too.
  • A wrong secret is refused with invalid_client. Only a private app may use this grant: a public app's client gets unauthorized_client.

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.

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.

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).
  • The organization uninstalls the app from My applications, with Uninstall. Its tokens are refused at once, and the app receives app.uninstalled if 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.