Authentication/OAuth lifecycle in Qlik Stitch

[Mohammed_Messaoudi]

Authentication & OAuth lifecycle in Stitch integrations

Stitch uses secure authentication methods to connect to SaaS sources and extract data. The most common method is OAuth 2.0, which provides token-based authorization.

Authentication methods in Stitch

• Basic Authentication: Used by some sources (e.g., databases) requiring static credentials (username/password).

• OAuth 2.0: Most modern SaaS sources (e.g., Google Analytics, Salesforce, Intercom) use OAuth, which authorizes access via tokens tied to a user account and permissions.​

• API Keys: A simpler method for certain sources (e.g., Stripe).

OAuth Lifecycle in Stitch

1. User authorization:

   • When you connect a SaaS source in Stitch, you’re redirected to the provider’s OAuth login page.

   • After authentication, you grant Stitch’s app access to specific scopes (permissions), defining what data Stitch can read.

2. Token generation:

   • The provider issues an authorization code, which Stitch exchanges for:

     • Access Token: Short-lived (minutes to hours), used for API calls.

     • Refresh Token: Longer-lived (weeks or months), used to renew access tokens automatically.

3. Token storage & use:

   • Stitch securely stores tokens (encrypted at rest and in transit).

   • Stitch uses the refresh token to keep integrations authorized without user intervention.

4. Token expiration & Revocation:

   • Access tokens expire quickly per provider settings.

   • Refresh tokens may expire or be revoked if:

     • Permissions change

     • The user deauthorizes Stitch

     • Security policies update

   • If tokens cannot be refreshed, data extraction fails with an authentication error. Stitch logs these errors and alerts users.

Impact of User Permissions

• Permission Changes: Downgrading or revoking permissions can block Stitch from accessing required endpoints.

• De-authorization: Disconnecting Stitch from the SaaS account revokes all tokens immediately.

• Role Changes: Switching roles (e.g., admin → read-only) can restrict Stitch’s ability to fetch data, causing API errors or failed syncs.

Common OAuth-related error examples

Error Message	Cause	Solution
"invalid_grant"	Token expired or revoked	Reauthorize Stitch integration
"insufficient_permissions"	User role changed or permissions restricted	Restore permissions or update token
"401 Unauthorized" / "expired access token"	Access token expired	Generate a new token
"refresh_token expired"	Refresh token disabled or expired	Reconnect and reauthorize the app

Environment

Stitch