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 |
Private apps: client credentials
Section titled "Private apps: client credentials"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:
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_inandaccess_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; withscope(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.
Both kinds
Section titled "Both kinds"- The client is confidential: the
client_secretstays 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), withWWW-Authenticate: Bearer(errors).
What you were granted
Section titled "What you were granted"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.