4.1.2 Integrations — OAuth & Permissions — Tokens and Scopes

OAuth & Permissions define how Praisma Hub securely connects to external platforms using delegated authorization. Integrations rely on OAuth flows to obtain scoped access without storing user credentials, ensuring compliance with platform policies and industry security standards.

OAuth Authorization Flow

Connections are established through platform-approved OAuth authorization flows. Users are redirected to the external platform to grant access and are returned with an authorization grant.

Flow characteristics:

User-initiated consent

Platform-hosted authentication

No credential handling by Praisma Hub

Authorization grants are exchanged for access tokens server-side.

Token Types and Storage

Integrations may use short-lived access tokens and long-lived refresh tokens depending on platform requirements.

Token handling rules:

Encrypted at rest

Never exposed to the client layer

Resolved only at execution time

Example secure storage:

EncryptedToken::store([ 'channel_id' => $channel->id, 'access_token' => $token, 'refresh_token' => $refresh ]);

Permission Scopes

Scopes define the exact permissions granted to an integration. Only the minimum required scopes are requested.

Scope principles:

Least privilege by default

Explicit user consent

Feature-based scope grouping

Example scope configuration:

{ "scopes": ["pages_read_engagement","pages_manage_metadata"] }

Scope Enforcement

Granted scopes are validated before every API operation. Attempts to execute actions outside the approved scope are rejected deterministically.

Example enforcement:

if (!$token->allows('messages.write')) { abort(403); }

Token Refresh and Rotation

Access tokens are refreshed automatically using refresh tokens where supported. Rotation occurs transparently without user intervention.

Rotation guarantees:

No downtime during refresh

Retry on transient failures

Immediate invalidation on revocation

Revocation and Disconnection

Users may revoke access at any time either from the platform or from Praisma Hub. Revocation immediately disables all associated operations.

Disconnection behavior:

Tokens invalidated

Scheduled jobs halted

Historical data retained

Error Handling

OAuth and permission errors are isolated to the integration layer. Clear diagnostics are provided without exposing sensitive details.

Security and Compliance

All OAuth operations are tenant-scoped. Audit logs record authorization, refresh, and revocation events. Token usage complies with external platform terms and applicable data protection regulations.