Oauth2 Amocrm Laravel Package

Technical Evaluation

Architecture fit. amocrm/oauth2-amocrm is a thin, framework-agnostic OAuth 2.0 provider for amoCRM, built on league/oauth2-client. It solves exactly one problem: the authorization-code handshake and access-token refresh against amoCRM's identity endpoints. It is not a Laravel package — no service provider, no publishable config, no facade, no queue/HTTP integration. For a Laravel codebase this is a library you wire up yourself, not a drop-in. It also does not cover the parts of an amoCRM integration that actually generate operational cost: token persistence, per-account base domains, API resource calls, rate limiting, webhook handling, and disconnect/revocation flows.

Integration feasibility. Composer-installable and PSR-18/PSR-7 compatible, so it slots into a standard Laravel HTTP stack. A realistic build in a Laravel app is 3–5 dev days plus QA: register a private integration in the amoCRM developer console (client_id/secret/redirect_uri), implement the redirect + callback controllers, design a token store, implement a refresh job, and add a per-account HTTP client wrapper. That is achievable work; the package removes maybe a day of it.

Technical risk.

Key questions for the vendor/spike.

1. Does the provider accept a dynamic base domain per account, or is it hardcoded to www.amocrm.ru?
2. What are the exact PHP and league/oauth2-client major-version constraints, and how do they interact with a Laravel 10/11/12 matrix?
3. Does it implement refresh-token rotation, and does it expose the refresh response cleanly enough for us to persist the new token atomically?
4. Is it intended to coexist with or replace the OAuth handling in amocrm/amocrm-api-library?
5. Is there a documented token-storage model (expiry, scope, account identifier) or is that entirely on the integrator?
6. What is the release cadence and issue-response history over the last 12 months?

Integration Approach

Stack fit. Laravel 10/11/12 on PHP 8.1+, Guzzle or any PSR-18 client, Redis for locks and token caching, MySQL/Postgres for durable token storage. The package will sit behind our own AmoTokenProvider contract so that swapping to the official API library's auth — or a hand-rolled client — is a one-file change. This adapter boundary is the single most important architectural decision here; it converts the package's thinness from a liability into a commodity.

Migration path. If we have no existing amoCRM auth, adopt this package behind the adapter and move on. If we already authenticate through amocrm/amocrm-api-library, do not add a second OAuth implementation — either consolidate on the official library or use this package for both, but pick one and delete the other. A split auth path is the most likely source of production incidents in six months.

Compatibility checks before commitment. PHP constraint resolution in CI, league/oauth2-client major version pinning, behavior with an account-scoped subdomain, token encryption at rest (Laravel encrypted cast or a KMS-backed store), and whether the library surfaces enough error detail on a 400/401 from the token endpoint to distinguish "expired" from "revoked."

Sequencing.

1. Spike (1 day): sandbox amoCRM account, complete the full connect → call → refresh → revoke loop manually.
2. Schema: oauth_tokens table keyed on account_id with base_domain, encrypted access/refresh tokens, expires_at, revoked_at, last_refreshed_at.
3. Adapter + service provider: bind the provider, resolve a per-account HTTP client.
4. Lifecycle flows: connect, callback, disconnect, and handling of the amoCRM uninstall/revocation webhook.
5. Refresh job: queued, per-account Redis lock, jittered, with a dead-letter path that flags the account as "reconnect required."
6. Middleware: 401 → single retry after refresh; rate limiter at the account level.
7. Observability, then rollout behind a feature flag to a small cohort of accounts first.

Operational Impact

Maintenance. Low surface area, but low community pressure-testing. Pin the version, vendor the source if the license permits (it does), and assign a named owner. Expect to occasionally patch the provider ourselves; budget a small annual maintenance allowance rather than assuming upstream responsiveness.

Support. The operational burden is not in the code, it is in the account lifecycle. Users will reconnect, revoke, change subdomains, and uninstall. Support needs (a) a runbook for "integration disconnected," (b) a UI path to re-authorize without raising a ticket, and (c) internal familiarity with OAuth 2.0 refresh semantics. Documentation from the package is thin; assume we write our own.

Scaling. Access tokens are short-lived (~20 minutes), so refresh is O(active accounts) per hour — fine on a queue, catastrophic if done synchronously in a request path. Cache tokens per account in Redis, serialize refresh with a per-account lock, add jitter, and keep the token store shared across horizontally scaled workers. amoCRM enforces per-account rate limits, so the client must be account-scoped, not global.

Failure modes and required instrumentation.

Ramp-up. A mid-level Laravel developer familiar with OAuth needs roughly half a day on this package; a team new to OAuth 2.0 needs 1–2 days including the refresh-rotation subtleties. TPM-level effort is small on build, medium on ongoing operations — the real cost is the per-account support surface, not the code.

Bottom line. Low-cost, low-risk-to-try, but low-signal and incomplete. Adopt it only behind an internal adapter, only if a one-day spike confirms dynamic base-domain support and clean refresh rotation; otherwise use the official amocrm/amocrm-api-library and avoid maintaining two auth paths. The package is a convenience, not a foundation — treat it as replaceable commodity code from day one.