Skip to content

Authentication

Every request carries an OAuth 2.0 access token in the Authorization header:

Authorization: Bearer <access token>

The token is an app's, for its installation in one organization: the request sees only that organization's data, and never acts as a person. How the app gets it depends on its kind (choose your path). Both use the same token endpoint, on the main host:

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

A private app belongs to one organization and is approved there once, through its install link (private apps). From then on its server asks for tokens with the app's own credentials:

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 is token_type, expires_in and access_token; no refresh token. The token lives 60 minutes: ask for a new one when it expires.
  • Without scope, the token carries every scope the installation was granted; with scope (space separated) it is narrowed to those.
  • No person, no browser and no redirect: your system needs no public HTTPS address to get tokens.
  • Before the installation is approved, after an uninstall or while the app is suspended, its tokens get a 401.

Details: tokens.

Public apps: authorization code with PKCE

Section titled "Public apps: authorization code with PKCE"

A public app is installed by many merchants, each from a consent screen in their organization (your app).

  • The flow is authorization code with PKCE (S256), required for every client: OAuth for apps.
  • Each installation has its own tokens, refreshed with grant_type=refresh_token.
  • The client is confidential: the client_secret stays on the app's server, never in public code, a browser or a mobile app. It is shown once and rotated from the app's Details tab.
  • A grant belongs to the organization: it keeps working after the person who approved it leaves, and ends only when the installation ends (the app uninstalled, retired or deleted); a suspension pauses it. The merchant sees every call on the app's page in Applications → My applications.
  • The app receives webhooks for each installation.
  • A missing, wrong, expired or revoked token gets a 401 (unauthenticated), with WWW-Authenticate: Bearer (errors).

GET https://api.connectato.com/v1/organization answers any valid token, with no scope: the organization (id, name, timezone) and the caller (caller.scopes, caller.app_id, and caller.store for a store app). Use it to check a token before the first real request.