Download the PHP package atlas-auth/atlas-php without Composer

Atlas PHP SDK

The official PHP backend SDK for Atlas — the secret-key Backend API client plus local session-token/JWT verification. It mirrors the TypeScript SDK (@atlas/backend) namespace-for-namespace, so the same 45 resource namespaces are available with the same method names.

• PSR-18 / PSR-17 transport. Runs on Guzzle out of the box, or any PSR-18 client you inject. No network is required to unit-test code that uses it.
• Local JWT verification. SessionVerifier verifies session tokens against cached JWKS with no call to Atlas on the hot path — the same design as the TypeScript verifier.

Requires PHP 8.1+.

Install

The Backend API client

Construct Atlas\Client with your instance secret key. Guzzle is auto-discovered, so the zero-config path needs nothing else:

Every resource method returns the decoded JSON as an associative array. Writes take an associative body and an optional idempotency key:

Pagination

Error handling

Any non-2xx response throws the most specific Atlas\Exception\* subclass, all extending AtlasApiException:

TransportException is thrown when no response is received at all; ConfigException on a bad configuration (e.g. an empty key).

The 45 namespaces

users, sessions, organizations, roles, permissions, oauthClients, resourceServers, ssoConnections, scimTokens, domains, waitlist, allowlist, blocklist, attackProtection, actorTokens, invitations, webhooks, signInTokens, auditLogs, jwtTemplates, apiKeys, oauthProviders, ssoOnboarding, scimProvisioning, fga, rateLimitPolicy, riskBasedMfa, botSignals, networkAcls, managedWaf, logStreams, branding, emailTemplates, smsTemplates, localizations, actions, billing, messaging, importExport, dataSubjectRequests, radiusClients, ltiPlatforms, instance, instanceSecurity, tokens.

Verifying session tokens

Atlas\Verify\SessionVerifier verifies a session JWT locally: RS256 against cached JWKS, exp/nbf with a 5-second clock skew, the issuer, and an optional azp allowlist. It never calls Atlas on the hot path — the revocation window is bounded by the 60-second token lifetime instead.

authenticateRequest() accepts a PSR-7 request or a plain, case-insensitive array<string,string> of headers. verify(string $token) is the direct form.

The online slow path

For the handful of operations where a 60-second revocation window is unacceptable (deleting an account, moving money), verifyOnline() asks Atlas whether the session is still live. It costs a round trip and fails closed — an outage returns invalid, never a stale local pass — so it is not the default.

JWKS caching

Keys are cached in-process. A token carrying an unknown kid triggers at most one JWKS refetch per minute, so a flood of random kid values cannot be turned into a flood of outbound requests. Key rotation is picked up automatically with no deploy.

Laravel

The SDK ships an optional, auto-discovered integration under Atlas\Laravel (install illuminate/support + illuminate/http — the base SDK requires neither). Atlas\Laravel\AtlasServiceProvider binds a container singleton SessionVerifier — so the in-process JWKS cache is reused across requests — and registers two route-middleware aliases. Publish the config and set your keys in .env:

Then gate routes. atlas.auth verifies the Authorization: Bearer header (or the __session cookie), 401s when absent/invalid, and on success attaches the verified result to $request->attributes->get('atlas') and $request->user(). atlas.permission reads the org role / permissions straight off the token:

Because the SDK is built on PSR-18/PSR-17, you can inject Laravel's HTTP client or any other conforming implementation instead of Guzzle by passing it to the constructor.

Symfony

An optional Symfony integration lives under Atlas\Symfony (install symfony/security-http + symfony/http-kernel). Register the bundle and point a firewall at the authenticator:

AtlasAuthenticator claims any request carrying a Bearer token or __session cookie, verifies it locally, and returns a SelfValidatingPassport whose user is an Atlas\Symfony\AtlasUser — identifier sub, roles ROLE_USER plus ROLE_<ORG_ROLE>, full claims via claims(). A missing/invalid token is a 401. Configure it with the ATLAS_* environment variables, or under an atlas key.

Testing

The SDK ships a PHPUnit suite that runs entirely against a mocked PSR-18 client — no network. Run it with:

License

MIT — see LICENSE.