Skip to content

OAuth for apps

Every app calls with OAuth 2.0 access tokens, for its installation in one organization. A public app is installed by each merchant from a consent screen, through the authorization code flow below; the installation gets its own tokens: an app installed in ten organizations holds ten sets of tokens, one each. A private app is approved once through its install link and takes its tokens with client credentials.

From the app's page, the Details tab in the partner portal (your app):

  • the client_id and client_secret. The secret is shown once and can be rotated; the client is confidential, so the secret stays on the app's server;
  • the registered redirect URIs (a public app's only);
  • the scopes the app requests.

The Connect block on the same tab shows the URLs below, ready to copy:

URL
Authorization (public apps) https://connectato.com/oauth/authorize
Token https://connectato.com/oauth/token
API https://api.connectato.com/v1

A public app's only flow is authorization code with PKCE, and PKCE with the S256 method is required for every client, confidential ones included.

  1. The merchant starts the installation from your app (your own connect button) or from the App store, which sends them to the app's install URL. The app generates a random code_verifier and code_challenge = BASE64URL(SHA-256(code_verifier)), without padding.

  2. The app sends the merchant to the authorization screen:

    https://connectato.com/oauth/authorize
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=<a registered redirect URI>
    &scope=read_orders write_shipments
    &state=<random value, checked on return>
    &code_challenge=<code_challenge>
    &code_challenge_method=S256
  3. The merchant signs in, picks the organization to install the app in and sees what it asks for: "Developed by <partner>", where the data goes, each scope explained in one sentence. The consent screen is shown every time; an app is never approved silently.

  4. Once approved, the merchant is sent to redirect_uri with code and state. The URI must be identical to one of the app's registered redirect URIs.

  5. The app's server exchanges the code for tokens at POST https://connectato.com/oauth/token, with the code_verifier.

Whoever approves must be a member of the chosen organization, allowed to manage the organization's connected apps and holding the permission behind each requested scope (scopes). An app that provides an integration (a store, for example) also needs the permission that integration asks for, managing integrations for a store (what the app provides); the consent screen lists what the app adds to the organization. An organization where the approver lacks one is shown with the reason and cannot be picked.

  • An app with no published version installs only in its partner's test organizations.
  • A published app installs in any organization. In the partner's test organizations the version being worked on (the draft) applies, with its scopes and redirect URIs; everywhere else, the published version (versions).

The authorization screen answers 400, with no redirect to the app, when:

  • code_challenge is missing or the method is not S256;
  • scope is missing;
  • a requested scope is not declared by the app (neither in the published version nor in the one being worked on) or does not exist. A scope removed in a new version gives a 400 once that version is published: the app must stop asking for it;
  • prompt=none: consent is asked every time.

A private app's client is refused here (unauthorized_client): it has no redirect URI and is installed through its link.

<?php
$verifier = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
Terminal window
curl -X POST "https://connectato.com/oauth/token" \
-d grant_type=authorization_code \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET" \
-d redirect_uri="$REDIRECT_URI" \
-d code_verifier="$CODE_VERIFIER" \
-d code="$CODE"

The response is the standard OAuth 2.0 one: access_token, token_type, expires_in and refresh_token.

The first request with the new token is GET https://api.connectato.com/v1/organization:

  • id (org_...) is the installation's organization. Keep it beside the tokens: webhooks name the organization by the same id, which is how you tell which installation a delivery belongs to;
  • caller.scopes are the scopes the merchant granted this installation. Read them here, never assume they are the ones requested: an older installation may hold fewer than your current version asks for;
  • caller.app_id is the app's client_id;
  • caller.store, for an app installed as one of the organization's stores, is that store: its integration_id, status and import_cutoff_date (store apps); null otherwise.
  • An access token belongs to the app's installation in one organization, never to a person.
  • When the access token expires, get a new one with grant_type=refresh_token at the same POST https://connectato.com/oauth/token, with refresh_token, client_id and client_secret. The new token stays bound to the same installation.
  • A new approval with a different set of scopes revokes the installation's old tokens: use the ones from the latest exchange.

A private app is installed in its one organization through its install link, approved there by an administrator (private apps). There is no authorization request and no redirect: the app's server asks for tokens with the app's own client ID and secret.

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" \
-d scope="read_orders read_shipments"
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
  • scope is optional, space separated. Without it, the token carries every scope the installation was granted; with it, the token is narrowed to those. A scope the installation lacks is never added.
  • The token lives 60 minutes (expires_in, in seconds). There is no refresh token: ask for a new one when it expires.
  • The token stands for the app's installation in its organization. A token taken before the installation is approved, after an uninstall or while the app is suspended gets a 401 on every call.
  • A wrong secret is refused with invalid_client. Only a private app's client takes this grant: a public app's gets unauthorized_client.

Code in every language: private apps.

Scopes are never widened silently. For a private app, the new scopes are approved through its install link (private apps); for a public app:

  • A published new version asking for more scopes changes no installation: each keeps the scopes it was granted until the merchant approves the new ones.
  • To get them approved, the app sends the merchant to https://connectato.com/oauth/authorize again, with the full list of scopes; the consent screen shows only what is new. The merchant can also start it themselves, from Applications → My applications, with Approve new permissions: the button opens the app's install URL, which restarts the OAuth flow.
  • Until then, a request needing a scope not granted gets a 403 (insufficient_scope). Check caller.scopes from GET https://api.connectato.com/v1/organization.
  • A version with fewer scopes narrows every installation as soon as it is published.

The merchant uninstalls the app at any time, from Applications → My applications, with Uninstall. The installation's tokens are revoked and the app always receives the app.uninstalled event, if it receives webhooks. Deleting the merchant's data after an uninstall is an obligation of the Partner agreement.