Download the PHP package axiam/axiam-sdk without Composer

On this page you can find all versions of the php package axiam/axiam-sdk. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package axiam-sdk

axiam/axiam-sdk (PHP)

CI Coverage Status Packagist Version PHP Version Docs

Official PHP client SDK for AXIAM — Access eXtended Identity and Authorization Management.

Platform documentation: https://ilpanich.github.io/axiam/ — getting started, the authorization model, the OAuth2/OIDC surface, and the operations guides. This README covers the SDK; the site covers the server it talks to.

Package identity

Install

From 1.0.0 the SDK is stable and follows semantic versioning: a breaking change to its public API comes only with a new major version.

What that promise means for a contract record. The SDK's models mirror the contract's records (CONTRACT.md, openapi.json). A contract record may add a member or widen a type with a minor bump — a new optional property on a response model, a new optional constructor parameter, a new case on an open enum — and a removal waits for 2.0.0. Two consequences for your code: construct the generated models with named arguments, because their parameters follow the schema's member order and move whenever the server adds one (1.1.0 moves some, and its change log says which); and give a match over an open enum an Unknown arm.

Supported PHP versions

Version Why this one
Floor 8.2 The oldest release still receiving security fixes — 8.1 reached end of life on 2025-12-31. This is the php constraint in composer.json, exposed as SupportedVersions::MIN_PHP.
Newest 8.5 The current release (2025-11), exposed as SupportedVersions::NEWEST_TESTED_PHP.

8.3 and 8.4 sit between the two and are supported.

The SDK is built against the floor, and runs on everything up to the newest. CI proves each separately: the gating matrix in sdk-ci-php.yml runs composer install and the full PHPUnit suite on 8.2 and on 8.5. Source-level gates that cannot depend on the runtime — composer validate, composer audit, PHPStan, the docblock-coverage gate and the TLS-bypass grep — run once, on the floor leg.

8.2 reaches end of life on 2026-12-31. The floor moves to 8.3 then; tests/VersionPolicyTest.php asserts the floor is a version that still receives security fixes, so this is a build failure rather than something to remember.

Until this change the declared floor was untestable by construction: the package published php: >=8.1, but the require-dev framework bridges (illuminate/support ^11, symfony/* ^7) require PHP ^8.2 themselves, so composer install was unsatisfiable on 8.1 and CI died before running a single test. The floor was advertised to every Packagist consumer and had never once been executed.

Axiam\Sdk\SupportedVersions exposes both ends as readable constants — see examples/version_compatibility.php for a runnable preflight. Composer enforces the lower bound at install time, but only at install time: --ignore-platform-reqs, a config.platform override, or a vendor/ tree built on one runtime and deployed onto another all get past it, and the mismatch then surfaces as a parse error on the first request.

Quickstart

See examples/login_mfa.php and examples/rest_authz.php for complete, runnable versions of this flow.

Organization-level principals (CONTRACT.md §5.2)

A completed login also reports whether the account it signed in is an organization-level principal — one whose record lives in its organization's reserved tenant, so its global grants apply in every tenant of that organization:

An ordinary tenant principal is a principal of exactly one tenant; changing the header for one of those produces a 403, so an admin UI checks this flag before offering the switch rather than discovering the answer from a failed request.

The flag is derived, never asserted: it is resolved server-side from the caller's own tenant record, it is not a constructor argument, and this SDK never sends it. It is false against a server older than contract 1.31, and false on the two pending login outcomes, where no principal has been established yet — the safe direction in every case.

Signing one in (§5.2.1)

The reserved tenant has a fixed slug, organization, the same in every deployment — so signing in as an organization-level principal needs no new surface, only the ordinary constructor:

Prefer that form. The server also reads a login body naming no tenant as "the organization's own scope", but §5 rule 2 still requires a tenant on the X-Tenant-ID header of every request after the login, so the client needs one either way.

What §5.2.1 forbids is the third possibility: an empty-string slug. Nothing can carry one, so tenant_slug: "" resolves nothing — and on /auth/opaque/login/start it fails on the workspace before the tenant's OPAQUE mode is read, so the 404 that means "OPAQUE is not offered here" never arrives and this SDK has no fallback to take. Sign-in then fails even against a tenant with OPAQUE disabled. The constructor rejects a blank $tenant or $orgSlug, whitespace included; a null $orgSlug stays fine, because that is the organization identifier being optional rather than blank.

Runtime requirements — read this before using gRPC or the AMQP worker (SC#3)

The REST transport (login/MFA/refresh/logout/checkAccess/can/batchCheck over HTTP) works on any PHP runtime, including standard PHP-FPM. This is the default and requires no special deployment.

ext-sodium is required (composer.json declares it). AXIAM signs with Ed25519, so local token verification (§10.1) and the SSF receiver (§32.7) verify through it, and the signed §33.2 CIBA request signs EdDSA with it. It is compiled into PHP by default; on a build made without it, token verification and the SSF receiver fail with a typed AxiamException naming ext-sodium rather than a fatal error.

gRPC and the AMQP consumer are different — they require a long-running PHP runtime (Swoole, RoadRunner, or a plain long-lived CLI process), not standard PHP-FPM:

Process supervision is your responsibility for the AMQP worker. php-amqplib (unlike the Go/C# sibling SDKs' AMQP clients) has no built-in automatic reconnection — if the broker connection drops (broker restart, network blip), the worker process exits rather than silently retrying forever. Run it under a process supervisor that restarts it on failure: systemd (Restart=on-failure), a RoadRunner worker-pool respawn, or a Docker restart: unless-stopped policy. A worker with no supervision will simply stop consuming messages after the first connection loss and never recover on its own.

A broker confirm is not evidence that AXIAM saw a message (CONTRACT.md §8, contract 1.60). A publisher confirm, or the broker's basic.ack of a publish, means only that the broker accepted the message; this SDK never treats it as proof that AXIAM decided a request or recorded an event. A server running in the minimal profile (AXIAM__AMQP__ENABLED=false) reads no AMQP queue at all — it consumes neither axiam.authz.request nor axiam.audit.events, whatever a broker holds — so against one use REST or gRPC. GET /health reports profile: minimal and lists amqp_authz and amqp_audit_ingestion under unavailable.

Contract conformance

This SDK conforms to contract 1.65: CONTRACT.md §1–§13 and §12.7, §14, §15, §17, §19, §20, §21, §22, §23, §24, §25, §26, §27 (§27.6.2 included), §28, §28.12, §29, §30, §31, §32, §33, §36 and §37, with §32.7 and §33.2 signed (ES256, EdDSA) — the signed form for those two algorithms; PS256 is not shipped, see CIBA below for why — including §6.1 mTLS, contract 1.3; §12 OIDC/SSO helpers, contract 1.4; §13 webhook-signature verification; the §17 decision memo and §19 telemetry hooks, contract 1.8; §28 MCP resource-server helpers, contract 1.48, see below — the binding, cross-language behavioral contract every AXIAM SDK implements: camelCase method names (§1) — including the gRPC-only getUserInfo operation (§1.1) — the AuthError/AuthzError/NetworkError typed exception hierarchy (§2, extended by the §12 OAuthProtocolError AuthError sub-type), non-browser X-CSRF-Token response-header capture (§3), a shared Guzzle CookieJar (§4), a required tenant constructor parameter with no default (§5), strict TLS with customCa as the only server-verification escape hatch (§6) plus optional client-certificate mutual TLS (§6.1), Sensitive-wrapped token redaction (§7), HMAC-SHA256-verified AMQP messages (§8), single-flight refresh concurrency safety (§9), framework middleware/subscriber integration (§10), declarative per-endpoint authorization helpers (§11, see below), OIDC/SSO relying-party helpers (§12, see below), and webhook-signature verification (§13, see below), the opt-in §17 decision memo (decisionMemoTtlMs) and the §19 telemetry hooks (telemetryHook, see examples/telemetry_hook.php), the §22 reactor runtime (reactorServe, see below), the §23 OPAQUE login path (loginOpaque, see below — conditional on ext-ffi and one shared library, which is PHP's alone among the eleven SDKs), the §24 WebAuthn relying-party layer with its §24.6a JSON bridge and, since contract 1.45, the session-less webauthnSetupRegisterStart/webauthnSetupRegisterFinish pair (see below), the §25 account-lifecycle and MFA-enrolment operations (see below), §26 Pushed Authorization Requests (see below), and the §28 MCP resource-server helpers — the RFC 9728 protected-resource metadata document and the RFC 6750 bearer challenge, opt-in and off by default (see below).

§24.6b — the linked-API ceremony helper — is deliberately absent. PHP runs on a server, which has no authenticator, and §24.6b rule 2 forbids emulating one in software: a "credential" held in process memory is not a second factor. The ceremony runs in the browser, and §24.6a's JSON bridge is the seam that carries the challenge out and the response back.

§28.12, §29, §30, §31, §32, §32.7, §33 and §36 are named rather than folded into a range because they landed after this SDK already stated its earlier sections: widening a range silently would turn a statement that was true when written into a different claim without anyone editing it. The §21.3.1 amendment of contract 1.58 — the seventh mtls_endpoint_aliases member, backchannel_authentication_endpoint — is decoded and honoured on an mTLS CIBA call; it is part of the §21 claim, not of §33's. Vector A is pinned as the vendored CONTRACT.md carries it, tenant_id queries included.

Manifest pruning: not offered in any namespace (§27.10) — nothing a manifest omits is ever deleted.

Contract 1.59 (§34) adds no section and changes no wire shape; its clarifications P1 – P12 bind the sections above, and this SDK follows them — the table below says how, where the contract left a choice. Contract 1.60 answers the questions the 1.59 ports raised (§34.4), adds three optional members to the §27 models and the federation.update_config null rule (§27.15), and expected_updated_at on §31's ScimTargetInput; its §35 (certificate revocation lists) is informative and has no SDK surface. The second table says what 1.60 changed here. Contract 1.61 (additive, §34.5) adds three members: Certificate.user_id and its two request members (§27.11 rule 5), SsfStreamInput.expected_updated_at with the three meanings of events_requested on an update (§32.2, §32.3 rule 4), and CibaPendingList.total_pending and truncated (§33.3 rule 16, a console surface this SDK does not model). The third table says what 1.61 changed here. Contract 1.62 (the 1.1.0 release, §34.6) adds the network management namespace (§36) and puts it in the manifest (§27.6.2), makes the device grant authenticate its client (§14.1), gives a stream a change-taking read-modify-write form (§32.2) and settles two rules about request members (§27.11 rule 5). Release 1.0.1 was never tagged: this is the first release to carry 1.61 as well, as 1.1.0 (its change log is merged into 1.1.0). The first table below says what 1.62 changed here.

Contract 1.65 (the 1.2.0 platform release, §34.9) adds no management operation (202 operations across 29 namespaces) and brings two things every SDK ports — native sign-in with a provider ID token (§37, loginWithProviderIdToken() and nativeNonce()) and the idp_hint input of oidcBegin()/oidcPar() (§12.1, §26.2 rule 8) — beside server-side changes that need no SDK work. The first table below says what 1.65 changed here.

Server floor: federation-config admin calls (federation.create_config, get_config, list_configs, update_config) of this 1.2-line SDK need an AXIAM server 1.2.0 or later: FederationConfigResponse::$nativeLogin is required from 1.2.0, and a response from an older server fails to decode.

Contract 1.64 (the 1.1.2 release, §34.8) adds no operation (202 operations across 29 namespaces) and records one rule SDKs port, one wording relaxation, and server-side changes that need no SDK work. The table headed "Contract 1.64" below says what 1.64 changed here.

Contract 1.65 — what changed here

Item (§34.9) Here
(a) native sign-in with a provider ID token (§37) AxiamClient::loginWithProviderIdToken() and nativeNonce(); see Native sign-in. Tests: tests/Contract165/NativeSignInTest.php, the thirteen of §37.9 under the contract's names
(b) idp_hint on the authorize-URL builder and on PAR (§12.1, §26.2 rule 8) oidcBegin(…, idpHint: …) emits axiam_idp_hint once; oidcPar(…, idpHint: …) pushes it in the body (defaulting to the hint the AuthorizationRequest was built with) and keeps the redirect to client_id and request_uri; tests/Contract165/IdpHintTest.php
(c) a replayed refresh token ends the session (§9) No code change. invalid_grant on oidcRefresh() is an OAuthProtocolError that is never retried, and the single-flight guard keeps one burst to one rotation; tests/Contract165/RefreshReuseConfirmationTest.php confirms it. This SDK stores no refresh token, so refreshing the same token from two places is the caller's defect to avoid
(d) client_id on exchanged tokens, (f) login.post_auth on native sign-in Informative; no SDK change
(e) the handoff redirect carries the spent start state No change. This SDK parses no handoff callback URL: ssoCompleteHandoff($code) takes the code, and the bundled Laravel and Symfony controllers handle only the OIDC callback and read state, code and error by name, so an extra state is tolerated; nothing here redeems, sends or forwards it
(g), (i), (j) default_idp, refresh_reuse_response, native_login Regenerated from the registry (§27.8): default_idp on the OAuth2 client models, RefreshReuseResponse and its member on OAuth2Policy, SetOrgSettings and TenantSettingsOverride, NativeLoginTrustRequest/NativeLoginTrustResponse on the federation config models. settings()->setOrg() is the plain replace: this SDK ships no composed read-modify-write form for settings, so pass refreshReuseResponse from the getOrg() read (->oauth2->refreshReuseResponse) when writing back, or an organization on refuse is moved to the server default revoke_session (the stricter direction). A member added to a generated model is a new constructor parameter, which breaks a positional call; name the arguments

Contract 1.64 — what changed here

Item (§34.8) Here
(b) a 429 rate_limit_exceeded on a device-code poll is waited out (§14.2 rule 9) deviceLogin() waits Retry-After as a minimum (in place of that round's interval, capped at the expires_in deadline), does not raise the interval, and polls again; devicePoll() still raises the OAuthProtocolError, which now carries retryAfterMs. Tests: tests/OidcDeviceFlowTest.php
(c) the refusal at plan names the member, and the value where the SDK keeps it (§27.6.2 item 4) The generated models keep the raw string of an open-enum member that decoded to Unknown (unknownEnumValue(), never rendered or sent); the refusal quotes it, and says the value is unknown when no raw string was read
§14.2 rule 6 (amended): a 5xx on the device poll is a transport failure whatever its body devicePoll() reads the status first: 500 {"error":"server_error"} is a NetworkError, §16-retried inside the poll (three attempts in total, never a 429) and outlived by deviceLogin()
§14.2 rule 9 (amended): the status decides, any 429 is the wait OAuthProtocolError::$httpStatus; a 429 whose body says slow_down does not raise the interval, and a body-less 429 honours Retry-After as a floor
(a), (d) to (j) Informative; no SDK change. This SDK parses no recovered gdpr.user_pseudonymized row and builds no AuditEventMessage
C163-18 a request retried after a refresh Carries the refreshed Authorization, X-CSRF-Token and Cookie: RefreshMiddleware is now pushed before AuthMiddleware; tests/Contract164/RetriedRequestHeadersTest.php
C163-19 /oauth2/ under a base URL path prefix AuthMiddleware anchors the /oauth2/ match to the base URL's path

Contract 1.63 — what changed here

Item Here
(a) no session cookie or X-CSRF-Token on /oauth2/* (§6.1 rule 11, §12.1 rule 3) AuthMiddleware drops both on every /oauth2/ request; tests/Contract163/OAuth2NoSessionCredentialsTest.php
(c) the AMQP audit producer refuses a reserved tenants./gdpr. action Not applicable: this SDK ships no helper that builds or signs an AuditEventMessage, only an audit-events consumer and the reactor's reply publisher
C162-04 an unrecognised open-enum value is never sent Generated open enums have toWire(), which raises ValidationError on Unknown; the refusal is local, before the request
C162-07 plan refuses an unknown open-enum value on an unstated member ManifestApi::plan() raises ValidationError for a network profile (GETs only)

Contract 1.62 — what changed here

Item (§34.6) Here
(l) the network namespace (§36) Twelve operations on $client->network() (also $client->management()->network()): listSegments, createSegment, getSegment, replaceSegment, deleteSegment, listProfiles, createProfile, getProfile, replaceProfile, deleteProfile, getPolicy, replacePolicy; 202 operations across 29 namespaces. The decision route POST /api/v1/network/decide is no SDK work and has no method
§36.4 the 409 sub-code ConflictError::getReasonCode() returns the body's reason_code verbatim (the vocabulary is open); null when the body has none
(n), (u), (v), (w) network in a manifest (§27.6.2) ManifestBuilder::networkPolicy(), networkSegment(), networkProfile(); see the network section
(o) eleven replace operations The three network PUTs are replace* and full-body, each carrying the version the caller read; their docblocks give the read-modify-write pattern
(m), (t) the device grant authenticates its client (§14.1) A configured secret is sent as client_secret in the form body at deviceAuthorize() and every devicePoll(); a certificate is presented on the connection; a public client sends none. Never Authorization: Basic. See the device section
(e), (g), (h) the stream form (§32.2) ReadModifyWrite::ssfStream($stream, $changes) is the change-taking form: it sends events_requested and the server's own updated_at string as read and cuts events_requested to a lowered events_allowed. The plain call (ssfStream($stream)) is the converter, and its documentation names the caller's duty. updateStream()'s docblock states the three meanings of events_requested
(f) an assigned null is "none" Already held: a PHP null on userId (both certificate requests) or expectedUpdatedAt (updateStream, scimTargets()->update) is the same as never setting it — the key is omitted and null is never sent
(i) the request user_id is an untyped string Already held: CreateCertificateRequest::$userId and SignCertificateCsrRequest::$userId are ?string; a malformed value reaches the server and its 400 is a ValidationError. Certificate::$userId is unchanged
(j) change-log line "wire-additive; source-breaking in Rust, Java, Kotlin and PHP, released as 1.1.0": a member added to a generated PHP model is a new constructor parameter, which breaks a positional call — see the change log
(d) CibaPendingList No SDK work, and not modelled

Contract 1.59 — the Phase 23 review follow-up (F-59-06)

Clarification Here
P1 poll never keeps a jti it does not return The second form: what was judged is returned, and a SET a key-fetch or store failure left unjudged is unrecorded and listed in SsfPollResult::$unjudged (with $unjudgedCause); after a store failure the store is asked nothing more for the batch, a later SET that fails verification is still refused and one that verifies is unjudged; the failure is raised instead only when no SET of the batch had been accepted
P4 the replay store ReplayStore::checkAndRecord() reports a failure by throwing, which accepts nothing (fail closed) and surfaces as a NetworkError with the store's exception chained; the default InMemoryReplayStore is unbounded in count, its entries expiring after the window
P6 key fetches A failed fetch — a fill and an expiry refresh included — and every unknown-kid refetch count toward the once-a-minute limit; a successful fill does not. The key cache expires 300 s after the fetch that filled it
P8 a 5xx on ciba_poll A NetworkError whatever its body (500 {"error":"server_error"} included), retried under §16 and outlived by cibaAwait
P10 cibaAwait's anchor The instant the initiate response was received, read from the injected CibaClock, which also supplies the waits, the §16 retry waits inside a poll included: a retry whose longest wait would reach the deadline is not sent
P12.1 / P12.2 unknown SCIM arms ScimTargetAuthUnknown / ScimTargetScopeUnknown keep the type and nothing else; they render for a log line and are refused locally on the request path
P12.4 the RFC 7592 replacement Built from what the read carried: a list the read lacked is not sent, a member of an unexpected shape goes back as read
P12.7 the signed form Claimed as "§33.2 signed (ES256, EdDSA)"

Contract 1.61 — what changed here

Row Here
§27.11 rule 5 Certificate::$userId On Certificate and GeneratedCertificate, ?string: null and an absent member (a server before 1.1.0) both decode as "no account named"; never required, never synthesised from metadata or the subject
§27.11 rule 5 request member CreateCertificateRequest::$userId and SignCertificateCsrRequest::$userId, sent exactly as given; the key is left out when unset, never null; the value is not judged locally (the server's 400 is surfaced)
§32.2 expected_updated_at SsfStreamInput::$expectedUpdatedAt, sent on updateStream exactly as given (the string) and absent when unset; a 409 is a ConflictError, one request, no retry
§32.2 events_requested on an update Absent resets to every allowed event, [] is sent as [], a list as given. ReadModifyWrite::ssfStream() sends the events_requested and the updated_at it read (and cuts the requested list to a lowered events_allowed)
§33.3 rule 16 CibaPendingList Not modelled: no registry operation returns it and the generator emits only the models its operations carry

Contract 1.60 — what changed here

Row Here
§31 expected_updated_at ScimTargetInput::$expectedUpdatedAt, sent on update exactly as given and absent when unset; ReadModifyWrite::scimTarget() fills it with the updated_at it read, so an edit made since answers 409 (ConflictError)
§27.15 window_minutes On CreateNotificationRuleRequest, UpdateNotificationRuleRequest and NotificationRuleResponse; passed through, never clamped
§27.15 allow_sha1_signatures, idp_metadata_signing_cert_pem On the three federation configuration models, sent only when set; a response without allow_sha1_signatures decodes as false
§27.15 note 8 The ten clearable members of UpdateFederationConfigRequest are string\|JsonNull\|null: null leaves the member out (unchanged), JsonNull::Null sends null (cleared)
§12.1 refresh scope OidcTokenSet::$scope is the refresh response's, never the original grant's
§21.5 discovery OidcConfiguration decodes the four revocation and introspection authentication members, each optional
§19.1 ssf_unjudged SsfUnjudgedEvent: a poll that returns with SETs unjudged reports their number and key_fetch or replay_store

Contract 1.53 – 1.58 — what this SDK ships

Section Here
§28.12 RFC 7592 client configuration readClientRegistration, updateClientRegistration, deleteClientRegistration on AxiamClient; Axiam\Sdk\Oidc\ClientRegistration
§29 SAML service providers $client->saml() — eleven generated operations with the §29.3 call-site notes; ParseSamlSpMetadata::fromUrl() / ::fromXml(), both-or-neither refused locally
§30 directory $client->directory() — six generated operations; bindSecret Sensitive; an explicit null on update through JsonNull::Null
§31 outbound SCIM targets $client->scimTargets() — six generated operations; credential Sensitive
§32 SSF streams $client->ssf() — five generated operations; authorizationHeader Sensitive
§32.7 SSF receiver helper $client->ssfReceiver(...) → Axiam\Sdk\Ssf\SsfReceiver::verifySet() / poll()
§33 CIBA cibaInitiate, cibaPoll, cibaAwait, cibaHandlePing on AxiamClient
§33.2 signed (ES256, EdDSA) CibaRequestSigner::fromPem() — ES256 and EdDSA; PS256 refused locally
§21.3.1 (amended) MtlsEndpointAliases::$backchannel_authentication_endpoint, the seventh alias

Carve-out — PS256 for the signed §33.2 request. This SDK's JOSE library, firebase/php-jwt, signs PS256 only through phpseclib 3, which is not a dependency of this package (the phpseclib a Composer install may pull in transitively for php-amqplib is version 4, whose namespace php-jwt does not load). Rather than depend on a transitive package or fail at the first request, CibaRequestSigner::fromPem(CibaSigningAlg::PS256, …) is refused locally with a ValidationError. A client that must sign CIBA requests registers ES256 or EdDSA.

Contract 1.51

Framework integration

Laravel — auto-discovered, zero-config

That's it. Laravel's own package auto-discovery reads this package's composer.json extra.laravel.providers entry and registers Axiam\Sdk\Laravel\AxiamServiceProvider automatically — no config/app.php edit, no bootstrap/providers.php entry. You get the axiam.auth authentication middleware and the axiam Gate ability (can:axiam,<resource>,<action> → 403 on deny) out of the box. See examples/laravel_app/README.md for the full middleware + Gate example, including a runnable 401/403/200 route.

Symfony — MANUAL registration is required

Unlike Laravel, the Symfony bridge does NOT auto-discover itself. Symfony has no equivalent to Laravel's extra.laravel.providers mechanism without a published Symfony Flex "recipe" (out of scope for this SDK). After composer require axiam/axiam-sdk, a Symfony application must perform two manual steps:

  1. Add Axiam\Sdk\Symfony\AxiamBundle::class => ['all' => true] to config/bundles.php.
  2. Tag Axiam\Sdk\Symfony\AxiamAuthSubscriber (kernel.event_subscriber) and Axiam\Sdk\Symfony\AxiamVoter (security.voter) in config/services.yaml.

AxiamBundle itself ships no container extension — registering the bundle alone does not wire the subscriber or voter; both manual steps are required. This is a genuinely different (not lesser) developer experience than Laravel's — do not expect composer require alone to do anything on Symfony. Full copy-pasteable config/bundles.php/config/services.yaml snippets and a runnable 401/403/200 controller example are in examples/symfony_app/README.md.

Local token verification (CONTRACT.md §10.1)

Both framework guards — the Laravel AxiamMiddleware and the Symfony AxiamAuthSubscriber — verify access tokens through one implementation, Axiam\Sdk\Auth\JwksVerifier::verify(), which applies the complete §10.1 minimum local-verification set. Every rule fails closed: a required claim that is absent, unparseable, or of the wrong JSON type is a rejection, never a skipped check.

# Claim What the verifier does
1 signature Verified against the org-wide JWKS with alg pinned to EdDSA before any kid lookup, so alg: none and HS-family confusion are rejected without ever consulting a key.
2 exp Required. No exp, or an exp that is not a JSON number, is rejected. An absent exp is a permanent credential, not an absent constraint.
3 nbf Honoured when present; an nbf in the future is rejected. An absent nbf is valid.
4 tenant_id Required and asserted against the configured tenant. An absent claim — or an empty configured tenant — is rejected.
5 iss Checked only when axiam.expected_issuer / AXIAM_EXPECTED_ISSUER is set. Unset by default.
6 aud Checked only when axiam.expected_audience / AXIAM_EXPECTED_AUDIENCE is set. Unset by default; both the single-string and array forms are honoured.
7 clock skew JwksVerifier::CLOCK_SKEW_LEEWAY_SECONDS — a named 60-second constant applied to rules 2 and 3. Deliberately not operator-configurable.
8 (no claim check) Not a claim this verifier decodes — §10.1 rule 8, "the guard decides on the CALLER's credential and no other", is a control-flow discipline for whoever calls this class. Both framework guards call verifyLocally(), never verifyLocallyOrFallback(), so a certificate- or DPoP-bound token the guard has no transport evidence for is always refused behind them — a bound token is never silently admitted as a bearer credential (CONTRACT 1.52 N1, C-12).
9 cnf (contract 1.51) A token carrying cnf is not a bearer token and MUST NOT be admitted without evidence satisfying every constraint it names. verifyLocally()/JwksVerifier::verify() has no transport to ask for that evidence, so it applies this rule with NONE presented — refusing every bound token, admitting every unbound one. AxiamClient::verifyWithProofs($token, $tenant, PresentedProofs) / JwksVerifier::verifyWithProofs() is the same check with real evidence YOUR OWN connection established.

What firebase/php-jwt does versus what §10.1 requires. JWT::decode() validates nbf/iat/exp and rejects a non-numeric exp — but only when the claim is present (isset($payload->exp) && …), so a token with no exp at all passes straight through it. Its is_numeric() test also accepts a quoted "1700000000", which is a JSON string rather than an RFC 7519 NumericDate. And JWT::$leeway is a public mutable static that any code in the process can set to an unbounded value. This SDK therefore enforces rules 2, 3 and 7 itself rather than inheriting the library's behaviour, and pins JWT::$leeway to its own named constant for the duration of every decode.

The X-Tenant-ID request header narrows; it never overrides. The token's tenant_id is asserted against the tenant the application was configured with. When the request also carries X-Tenant-ID, that header must agree with the verified claim — it can never select which tenant is expected, because it is attacker-controlled and doing so would make the check vacuous.

iss and aud are conditional and default to unset; no issuer or audience is hardcoded anywhere. Configure them when your deployment has an expectation to assert — an app guarding a user-facing resource server should generally expect axiam:user:

Declarative authorization helpers

CONTRACT.md §11 adds a per-endpoint authorization layer on top of the §10 authentication guard above: three PHP 8 attributes in Axiam\Sdk\Attributes — #[RequireAuth], #[RequireAccess(action: ..., resourceParam: ...)], and #[RequireRole(...)] — enforced by a single shared Axiam\Sdk\AccessEnforcer that BOTH framework bridges delegate to, so Laravel and Symfony applications get byte-identical semantics.

Semantics (identical in both bridges, CONTRACT.md §11.2): require_access runs strictly AFTER authentication — a missing identity is 401, never a second token verification. The resource id is a UUID resolved from (in order) a static literal, a route parameter, or a resolver callback; unresolvable is 400, never a silent allow. A denied check is 403; a transport failure fails CLOSED with 503 (never allows). checkAccess is always called with the REQUEST's authenticated user_id as the subject — not whatever session the shared AxiamClient itself might separately hold. #[RequireRole(...)] is a LOCAL, no-server-round-trip check against the verified identity's roles — coarser than #[RequireAccess] and not a substitute for it. No decision is ever cached, and no token material appears in any error output.

OIDC / SSO relying-party helpers (CONTRACT.md §12)

Thirteen operations, directly on AxiamClient, let this SDK act as an OIDC/OAuth2 relying party against AXIAM's own OIDC provider — "Login with AXIAM" (authorization-code + PKCE), service-account client_credentials, token introspection/revocation, upstream-IdP federation SSO, and — as of contract 1.38 — the public "Sign in with X" buttons:

Method Wire call What it does
oidcDiscover() GET /.well-known/openid-configuration Fetch the discovery document (cached per origin, ≥5 min TTL, single-flight).
oidcBegin($configuration, $redirectUri, scope: ..., extraParams: ...) (none — pure local computation) Build the authorization URL + a fresh state/nonce/PKCE code_verifier.
oidcExchange($code, $codeVerifier, $redirectUri, $nonce, ...) POST /oauth2/token (authorization_code) Exchange a code for a token set; validates the ID token in full (§12.4).
oidcRefresh($refreshToken, ...) POST /oauth2/token (refresh_token) Refresh an OIDC token set — distinct from, but §9-guard-sharing with, refresh().
loginClientCredentials(...) POST /oauth2/token (client_credentials) Service-account machine-to-machine login.
introspect($token, ...) POST /oauth2/introspect RFC 7662 — is this token active, and what does it carry?
revoke($token, ...) POST /oauth2/revoke RFC 7009 — revoke a token (idempotent: any 200 is success).
ssoStart($federationConfigId, $redirectUri, ...) POST /api/v1/auth/federation/oidc/start Step 1 of upstream-IdP federation SSO.
ssoComplete($state, $code) POST /api/v1/auth/federation/oidc/callback Step 2 — session arrives as Set-Cookie, captured via the §4 cookie jar.
ssoProviders($orgId, $orgSlug, $tenantId, $tenantSlug) GET /api/v1/auth/federation/providers Which "Sign in with X" buttons to render. Identifiers go in the query string, not a body. An empty list is a success — see below.
ssoStartOauth2($federationConfigId, $redirectUri, ...) POST /api/v1/auth/federation/oauth2/start Step 1 through a plain-OAuth2 upstream (GitHub, Facebook, generic_oauth2). PKCE is mandatory here and is generated and held server-side.
ssoCompleteOauth2($state, $code) POST /api/v1/auth/federation/oauth2/callback Step 2 of the OAuth2 variant; same Set-Cookie session and §3 CSRF capture as ssoComplete().
ssoCompleteHandoff($code) POST /api/v1/auth/federation/handoff Redeems the single-use axiam_handoff code the SAML and Apple flows deliver. Valid 60 s, redeemable once; a 401 is terminal and is never retried.

What the discovery document models, and what is optional in it (§12.1, §21.5)

OidcConfiguration models a curated subset of the OIDC Discovery 1.0 / RFC 8414 document, and the optionality is the SDK's rather than the schema's. AXIAM marks nearly every member required; this type marks one required only where a missing value would leave the SDK with nothing to do but guess a URL. So the conditionally-advertised endpoints (device_authorization_endpoint, pushed_authorization_request_endpoint, end_session_endpoint) are nullable — §12.7.2 rule 1 forbids synthesising them from the issuer — and a document from a non-AXIAM OP still parses.

Contract 1.42 adds two capability lists, both nullable here even though AXIAM marks them required:

Property Advertised by AXIAM Why it is optional in this SDK
code_challenge_methods_supported ["S256"] RFC 8414 §2 defines no default, so absence does not mean S256 (§21.5) — it means the document says nothing about PKCE at all.
token_endpoint_auth_signing_alg_values_supported ["PS256", "ES256", "EdDSA"] Same, and informational either way: §12.1 note 3 pins this SDK to client_secret_post, so it never signs a client assertion.

null means the member was absent; an advertised [] survives as [], because a server saying "none of these" is a different fact from a server saying nothing.

A related 1.42 change is a rationale, not a rule: client_secret_basic is now accepted server-side and advertised in token_endpoint_auth_methods_supported. This SDK does not change — §5 rule 3 still forbids an Authorization: Basic header on /oauth2/*, because the two methods carry the identical credential and the header is the channel reverse proxies and APM agents log by default. An advertisement is a statement about the deployment, not an instruction to the client.

The four public login-provider operations, and their rules (contract 1.38)

An empty provider list is a success (§12.1 note 9). An unknown organization, a known one with nothing configured, and a request naming no workspace at all all answer 200 with an empty array. ssoProviders() returns every one of them as an ordinary result and never throws: the endpoint is deliberately shaped so it cannot be used to enumerate organization or tenant slugs, and telling the three apart client-side would rebuild that oracle. For the same reason ssoProviders() is the one federation operation that does not throw client-side when no workspace resolves — it sends the request. You learn you named the workspace wrongly at the start operations, where every failure is a uniform 401.

protocol selects which start operation to call (§12.1 note 10) — never providerKind, which is branding:

$provider->protocol call
FederationProvider::PROTOCOL_OIDC_CONNECT ssoStart()
FederationProvider::PROTOCOL_OAUTH2 ssoStartOauth2()
FederationProvider::PROTOCOL_SAML the SAML login endpoint — not a §12 vocabulary operation

The server refuses a mismatch with 400 rather than accepting it silently, so a client that assumes OIDC fails on every GitHub button. An OAuth2 provider also issues no ID token: the server authenticates by calling a configured userinfo endpoint, so there is no signature, no nonce and no aud — a distinction a UI rendering these buttons should make visible.

FederationProvider is modelled faithfully — id, providerKind, displayName, protocol, hasBundledMark, inherited, and the nullable buttonIcon (a data: URL, null for most providers). Inheritance from the organization is resolved server-side (§12.1 note 13): pass back the workspace and the id ssoProviders() gave you, and compute nothing locally. inherited is reported so an admin surface can show that a provider is not the tenant's to edit.

A 400 from a start call is a configuration refusal (§12.1 rule 12a). On the SAML and Apple flows the identity provider never validates the SPA $redirectUri, so the server confines it to its own issuer origin plus AXIAM__AUTH__SSO_SPA_ORIGINS. That refusal surfaces as NetworkError — §2's 400 row, the taxonomy's configuration/programming-error member, as distinct from the AuthError a 401 gets — and is not retried, because the same origin will be refused again. Never build a $redirectUri out of anything the identity provider supplied.

The caller owns the login state (§12.3 rule 1). oidcBegin() returns state, nonce, and a Sensitive-wrapped codeVerifier; the SDK stores none of them in any implicit cache. Persist all three yourself between the redirect and the callback (your own HTTP session, or Axiam\Sdk\Oidc\MemoryOidcStateStore — a single-use, 10-minute-TTL reference OidcStateStoreInterface implementation the Laravel/Symfony glue below uses). state/nonce are plain strings (not secrets, §12.3 rule 2); codeVerifier, access_token, refresh_token, id_token, and client_secret are always Sensitive-wrapped (§12.5) and redacted from __toString()/var_dump()/json_encode().

"Login with AXIAM" framework glue (optional, off by default on both frameworks — see examples/laravel_app/oidc_routes.php / examples/symfony_app/oidc_services.yaml + oidc_routes.yaml):

Native sign-in with a provider ID token (CONTRACT.md §37)

A mobile or desktop app that holds the ID token a Google, Apple or Facebook native SDK produced presents it to AXIAM's token endpoint and receives this client's ordinary token set. One request, no browser. It is not token exchange (§15 refuses ID tokens), and neither is a fallback for the other.

Choosing the provider for a browser sign-in (idp_hint, contract 1.65)

The hint is emitted as axiam_idp_hint, once, and only when set; only emptiness and length (256 bytes) are checked, with an \InvalidArgumentException. An unresolvable hint is ignored by the server. There is no kc_idp_hint.

Device authorization grant (CONTRACT.md §14)

RFC 8628 — signing in a device that cannot show a browser: a TV, a CLI, a headless commissioning tool.

deviceAuthorize() and devicePoll() are also public, for an application driving its own loop. The polling rules are where implementations go wrong:

deviceCode is Sensitive; userCode deliberately is not — it exists to be read aloud, and wrapping it would defeat the one thing it is for.

The device client authenticates the way it is configured to (§14.1 rule 2, contract 1.62). Since AXIAM 1.1.0 both device endpoints authenticate the client by the method it is registered for, as /oauth2/token does:

deviceLogin() takes an injectable $sleep (seconds), $now (a clock, in seconds) and $retrySleep (milliseconds: the §16 waits inside a poll), so the §14.2 interval arithmetic and the in-poll retries are testable exactly rather than in wall-clock time. A 5xx or transport failure on a poll is retried inside it (three attempts in total, never a 429), and a retry is never sent after the expires_in deadline: a wait that would reach it is not started. Without $retrySleep those waits are really slept, whatever $sleep is, because Retry-After is a floor. Per §14.3 rule 4 it returns the token set; $adoptAsCredential is the same opt-in flag loginClientCredentials() uses.

Token exchange (CONTRACT.md §15)

RFC 8693 — a service holding a user's token exchanging it for a narrower one before calling the next service.

To delegate rather than impersonate, pass an actor token, and make it the exchanging client's own client_credentials token (§15.2 rule 9, contract 1.60) — the server answers any actor token not issued to that client 400 invalid_request (actor_token was not issued to the exchanging client):

Most of what this method does is refuse to be helpful:

External-IdP subject tokens (CONTRACT.md §15.7)

The same method exchanges a token minted by a trusted external IdP — a partner's Entra, Okta or Keycloak — for an AXIAM token scoped to what the resolved AXIAM user may actually do. There is no separate operation:

The operator guide is docs/api/federated-token-exchange.md.

UMA 2.0 — Protection API and ticket grant (CONTRACT.md §20)

The resource-server side of User-Managed Access: register what you guard, ask the authorization server what a caller would need, and redeem the resulting ticket.

…and on the client side, having caught that 401:

The rules this surface exists to enforce:

Emitting the challenge from the §11 enforcer

Both framework bridges delegate every §11 decision to one AccessEnforcer, so a UmaChallenger handed to that enforcer covers Laravel and Symfony alike:

Two properties are deliberate, and both are asserted by counting Protection API requests:

The requested scope is the AXIAM action, so the ticket asks for exactly the authority that was refused and the engine's deny rules keep applying to whatever RPT comes back.

Both halves run in examples/uma_resource_server.php and examples/uma_client.php.

Logout — RP-initiated and back-channel (CONTRACT.md §12.7)

logoutUrl() builds the redirect; verifyLogoutToken() validates a token the OP pushed to your back-channel endpoint.

The verifier is where the security weight sits — the input arrives unsolicited and instructs you to terminate a session. It checks the signature (same JWKS path and same EdDSA/kid discipline as §12.4), iss, aud, that events carries the back-channel-logout key (the only thing separating a logout token from an ID token), that nonce is absent (its presence is how an ID token gets replayed as one), that something is named, and freshness.

It returns sid/sub/jti rather than a bare bool: you have to know which session to end. Dedup on jti yourself — delivery is at-least-once, so a valid token legitimately arrives twice; the SDK has no durable store and an in-memory guard would silently drop a real second logout after a restart.

Decision reason codes (CONTRACT.md §11 rule 9)

AccessDecision::$reasonCode distinguishes no_grant ("ask an admin for access") from denied_by_rule ("an admin has already decided") — opposite instructions to the person on the other end, which is why the contract forbids collapsing them into a bare false.

checkAccess()/can()/batchCheck() keep returning bool: those signatures predate the field and cannot carry it. checkAccessDecision() and batchCheckDecisions() return the full decision. ReasonCode holds the three defined values as class constants rather than an enum, so an unrecognised code is surfaced verbatim and never changes $allowed.

Webhook signature verification (CONTRACT.md §13)

AXIAM signs every webhook delivery with a Stripe-style signed timestamp. Verify it with AxiamWebhooks::verify() before trusting a payload:

The raw body is mandatory. The MAC covers the exact bytes AXIAM sent, so json_encode(json_decode($body)) — which can reorder keys, change whitespace, or re-escape / as \/ — will fail verification even though the payload is semantically identical. In Laravel use $request->getContent(); in Symfony, $request->getContent(). Never re-encode.

Behaviour: HMAC-SHA256 over <timestamp>.<raw_body>, compared in constant time (hash_equals) on the decoded bytes; a header carrying no v1 is always a failure; the freshness window is two-sided and defaults to 300 seconds, so a future-dated timestamp is rejected just like a stale one. Multiple v1 values are accepted to support secret rotation. Use the X-Axiam-Delivery header as an at-least-once dedup key — a retry replays a valid signature inside the freshness window.

Reactors — AMQP extension actors (CONTRACT.md §22)

A reactor is an external process that subscribes to named hook events on the AXIAM bus and answers back — allow, deny, or a field-allow-listed mutation — inside a timeout the server declared. Zitadel Actions and Keycloak SPIs solve the same problem by loading third-party code into the authorization server; a reactor stays outside it, reachable only through a signed reply schema the server validates before it believes a word of it.

Binding handlers per event (§22.14)

The switch above is the shape every multi-event reactor grows, and its fall-through — return ReactorAnswer::allow() — answers on behalf of code that never ran. That is the defect §22.10 rule 2 forbids the runtime from committing, relocated into your file where the rule does not reach it: an operator who set fail_closed on the registration has it defeated there.

ReactorHandlers is §22.14's declarative form, and it uses the same attribute mechanism the §11 #[RequireAccess] helper already uses:

Closures work too — (new ReactorHandlers())->bind(ReactorEvents::TOKEN_PRE_ISSUE, $fn) — and both spellings are governed by the same rules. It is pure sugar: handler() returns exactly the callable ReactorServer already takes. It opens nothing, verifies nothing, signs nothing, does not filter a patch, and a handler's own throwable reaches the runtime unchanged so nothing is published.

reactorServe() verifies every delivery before the handler sees it — key version, MAC, freshness, nonce, in that order — then signs the reply with the same tenant subkey. §8's HMAC runs in both directions here: a reply is an instruction to change a token or refuse a login, so an unsigned or stale one is not a weak reply, it is not a reply at all.

Five things this runtime does that are easy to get wrong, and that are asserted against the server-generated vectors in tests/Fixtures/reactor_v2_reference_vectors.json rather than documented and hoped for:

The event registry, its per-event mutable-field allow-lists and §22.8's strictest-wins failure-policy composition are mirrored locally (ReactorEvents::all(), ReactorEvents::defaultFailurePolicy($events)) because the delivery path validates against them with no network available; GET /api/v1/reactors/events serves the live copy.

Not hookable, and not offered anywhere in this SDK: the hot-path decision operations (the authorization check, the batch check and token introspection) are absent from the registry by design — §22.7 writes this as a MUST NOT because a reactor round-trip is milliseconds and the check path's budget is microseconds. An application that needs external input on an authorization decision writes a deny grant, which the engine evaluates in the hot path at hot-path cost.

timeout_ms reaches the handler as $event->timeoutMs and bounds the reply: work whose window has already closed is abandoned rather than answered late. Telemetry (§19) is available through the telemetryHook constructor argument — and worth wiring, because a fail_open timeout produces allow and an audit record, so reactor health must never be inferred from the outcome alone.

Like the §8 consumer, a reactor is a long-running CLI process, never an FPM request, and php-amqplib has no built-in reconnection: when the broker session ends reactorServe() returns and a process supervisor restarts the worker. That is a deliberate deviation from the Go/Java runtimes' in-process reconnect loop and the same posture this SDK already documents for the AMQP worker above. $server->stop() is safe from a pcntl signal handler: the delivery in flight is answered before the loop returns (§18).

See examples/reactor/reactor.php.

OPAQUE (CONTRACT.md §23) — conditional on ext-ffi and one shared library

loginOpaque proves the password to the server without the password — or anything from which it can be cheaply recovered — ever crossing the wire. The server stores a registration record sealed under a tenant-wide oblivious PRF seed, and what travels is a blinded group element and a MAC, neither useful without both.

It takes the same arguments as login() and returns the same LoginResult, MFA branch included, so switching a tenant to OPAQUE needs no change to how the result is handled. A runnable end-to-end example is examples/opaque_login.php.

Unlike the SRP-6a it replaces, there is no separate server-proof step and nothing has been dropped: RFC 9807's AKE authenticates the server during the handshake, so opening KE2 is the proof that it holds the record.

PHP went from two conditions to one

This was the SDK where §23 hurt most, and the change is worth spelling out.

The SRP client needed two things, and the second was the bad one:

  1. ext-gmp or ext-bcmath, because PHP has no native arbitrary-precision integer and SRP is 2048- to 4096-bit modular exponentiation.
  2. A tenant configured for pbkdf2_sha256 — because no PHP runtime offers Argon2id with a caller-supplied 32-byte salt. sodium_crypto_pwhash requires exactly 16, password_hash() generates its own. AXIAM's default KDF was, for PHP, simply unreachable, and the honest advice was to weaken the tenant's configuration for PHP's benefit.

Both are gone. The key stretching now happens inside libaxiam_opaque_ffi, so a true from opaqueAvailable() means every tenant works — including the default one — and no tenant needs reconfiguring on PHP's account.

What remains is having the library, which is two things that are really one:

1. ext-ffi. Not guaranteed on any runtime, and disabled outright on some shared hosts.

2. libaxiam_opaque_ffi. A Rust cdylib published as a per-platform asset on the axiam release page, not a Composer package — there is no cross-language registry to put it on. Put it on the system library path, or:

opaqueAvailable() reports both as one answer, and reports rather than throwing — so an application chooses the login path before attempting one rather than discovering the gap mid-exchange. It also calls into the library rather than merely loading it: FFI resolves symbols lazily, so a probe that only opened the file would report "present" and then fail at login against some other library that happened to share the name.

The protocol is not implemented here

CONTRACT.md §23.1 forbids an SDK from writing its own OPAQUE. SRP-6a was arithmetic every language can express — which in PHP meant ~800 lines across two bignum backends, plus the pbkdf2_sha256 limitation on top. OPAQUE is not: it needs an oblivious PRF, hash_to_curve, expand_message_xmd, an envelope construction and a three-message AKE, and eleven independent implementations of that is eleven chances to be subtly and silently wrong in a way that still interoperates until it does not.

Axiam\Sdk\Opaque therefore contains no cryptography. It is an FFI binding to the same implementation the AXIAM server links.

What this buys, and what it does not

OPAQUE closes holes TLS 1.3 does not:

It does not protect against a compromised AXIAM server, and this SDK does not claim it does.

Tenant policy, and the errors that are not credential failures

opaque_mode is an organization baseline a tenant may tighten:

mode login() loginOpaque()
disabled (default) works NetworkError — the endpoint answers 404
optional works works
required AuthzError works

Which exception you get is most of what this SDK owns on this path:

condition exception why
tenant has OPAQUE disabled NetworkError a property of the tenant, not of any user — fall back to login()
ext-ffi or the library absent NetworkError a fact about this runtime, raised before any request is sent
server named a KSF this build cannot perform NetworkError a configuration problem; substituting one would surface as a wrong password
/start response missing ke2 NetworkError malformed response
envelope did not open / KE2 did not verify, mode: "required" or no mode AuthError the whole of the credential check
envelope did not open / KE2 did not verify, mode: "optional" whatever login() returns or raises retried over login() first — see below
tenant refuses password login (login()) AuthzError the credentials were never examined

That AuthError covers both halves of the mutual authentication: a wrong password, an account that does not exist, a server that does not hold the record, and an account with no registration record at all are indistinguishable by design. Nothing is sent to login/finish in that case (§23.4 rule 7).

What happens next depends on the mode field the login/start response carries — the tenant's opaque_mode — and on nothing else (contract 1.29):

mode is not downgrade protection, and do not read it as one: a hostile endpoint that wanted the plaintext could simply answer 404, which sends a caller to login() whatever it puts here. required is what closes that, server-side, by refusing /auth/login before it examines any credential.

required refuses every principal in the tenant, not only the enrolled ones. Splitting the response on whether an account has a record would turn /auth/login into an enumeration oracle costing one junk password per name. Operators turn it on last, after a password-reset campaign.

Enrolment

The server cannot build a registration record, so any request that sets a password has to carry one. opaqueEnrollment() produces the opaque object for POST /api/v1/users, /auth/password/change, /auth/reset/confirm and /admin/bootstrap:

Note the parameters that are gone. There is no $identity: the SRP version required the account's username, an email there produced a verifier no login could ever satisfy — and renaming a user invalidated their verifier outright. A record binds to a credential identifier the server chooses, so neither is true any more. There is no $group or $params either: those come from the register/start response, so a caller cannot pick a cost the server will not honour.

Unlike srpEnrollment() this performs I/O — one register/start round trip. The envelope is sealed under the server's oblivious PRF, so there is no offline computation that produces a valid record.

Cost

loginOpaque() runs the tenant's key-stretching function: Argon2id at 19 MiB and t=2 by default, which is tens to hundreds of milliseconds of CPU plus that memory, per login attempt. That cost is the point — it is what makes a stolen record expensive to attack even by someone holding the OPRF seed. On a request-per-process runtime it lands squarely in the request; size max_execution_time and any upstream timeout accordingly. It is not a cost login() has.

Cryptographic parameters

The ciphersuite is OPAQUE-3DH over ristretto255 with SHA-512, HKDF-SHA-512 and HMAC-SHA-512, fixed AXIAM-wide. It is not negotiated and not read from the server: a client that accepted a suite from the endpoint it is authenticating would be accepting a downgrade.

The key-stretching function is the server's to name, per exchange, and is honoured as given rather than cached or defaulted. argon2id and scrypt are accepted; anything else — including pbkdf2_sha256, which was SRP's PHP-only fallback and is not an OPAQUE KSF at all — is refused rather than substituted. Costs outside the bands this SDK will act on (memory_kib 8 MiB–1 GiB, iterations 1–10, parallelism 1–16, log_n 14–20, r/p 1–16) are refused too.

Zeroization

PHP strings are immutable and the runtime copies them freely, so this SDK cannot clear the password. §23.3 rule 8 requires saying so rather than implying a guarantee it cannot keep. What it does do is never put the password in a request body, and never log it.

WebAuthn / passkeys (Axiam\Sdk\Webauthn, CONTRACT.md §24)

Eight wire operations, two ceremonies, and one thing this SDK deliberately does not do.

The server chooses every option and verifies every response; this SDK passes both through byte-for-byte (§24.0). WebauthnChallenge::$challenge is a plain decoded array, not a modelled type: no defaulting, no validation-that-rejects, no re-encoding. On the way back the *Finish body is assembled as text, splicing the caller's response string in unmodified — decoding and re-encoding it would round every number through a float and hand the server a byte sequence the authenticator never signed.

The browser half, via the §24.6a JSON bridge

requestJson() returns the inner options object — the publicKey wrapper belongs to the DOM's CredentialCreationOptions, and the platform JSON APIs do not want it. A mobile client relaying Android's registrationResponseJson uses the same two seams.

Passing something that is not JSON, or is not a JSON object, raises AuthError client-side with no wire call: the SDK will not POST a body it already knows the server cannot verify.

The two authentication ceremonies are different flows (§24.2)

webauthnAuthenticateStart()/Finish() is a second factor — it continues a login() that answered mfaRequired with "webauthn" among its methods, and the challenge token names the user so the server can send an allowCredentials list. webauthnDiscoverableStart()/Finish() is a primary factor: nothing precedes it, allowCredentials is empty, and the assertion itself identifies the user. They are not one operation with an optional token — merging them reproduces a bug the server already fixed, which is why the token is a required argument on one and absent from the other.

One difference a reactor author will ask about: discoverable/finish fires the login.post_auth hook event (§22.5) and authenticate/finish does not. The latter continues a login already gated at its password step; the former has no such step.

A passkey or security key as the first factor (§24.1, §25.2, contract 1.45)

webauthnSetupRegisterStart()/webauthnSetupRegisterFinish() are the WebAuthn twin of mfaSetupEnroll()/mfaSetupConfirm(): reached when login() returns LoginResult::$mfaSetupRequired because the tenant requires MFA and this account has none yet. A user of an enforcing tenant is no longer required to own a TOTP app to get in.

This pair takes no session, and this SDK never attaches one — the setup token is the only credential, exactly as mfa_setup_enroll/mfa_setup_confirm take none. Unlike webauthnRegisterStart()/Finish(), calling these never requires being signed in, and the wire call carries neither the session's Authorization header nor any cookie the shared jar already holds, even when the client happens to be signed in as someone else at the time.

webauthnSetupRegisterFinish() adopts credentials exactly as mfaSetupConfirm() does (§25.2 rule 2): both are the completion of the login login() interrupted, both answer the same LoginSuccessResponse, and both leave the client in the same signed-in state — the axiam_access/axiam_refresh/axiam_csrf cookie triple, the captured CSRF token, and a cleared §17 decision memo. A caller who chose a passkey over TOTP ends up exactly as authenticated as one who did not.

The account whose first factor is being enrolled is named by the setup token, never by the caller — there is no $userId parameter on either call. The server refuses an account that already has a factor with the same answer mfaSetupEnroll() gives: a setup token adds the first factor, never a second.

Saying something useful when a ceremony fails (§24.6b rule 5)

AlreadyRegistered is the exclusion list doing its job, and the only classification whose remedy is "use a different device" rather than "try again". Cancelled covers both an explicit refusal and a silent timeout — the spec deliberately refuses to distinguish them, because telling a website which one happened leaks whether an authenticator was present — so its copy does not accuse anyone of cancelling.

Two error rows that are not the §2 defaults (§24.4)

Session cookies: as of contract 1.28 both *Finish authentication calls set the axiam_access / axiam_refresh / axiam_csrf triple alongside the token body, so a completed ceremony leaves the client signed in for every cookie-driven call that follows (§24.3).

Worked end to end in examples/webauthn_passkeys.php.

Account lifecycle and MFA enrolment (Axiam\Sdk\Account, CONTRACT.md §25)

Ten operations covering the things a user does to their own account — none of which is administration, and all of which were previously reachable only by hand-rolling HTTP.

LoginResult gained two properties with defaults rather than changing shape, so every pre-1.28 construction still works and still reads false. Handle the new outcome anyway. A tenant that turns on required MFA will start returning it, and a client that only branches on mfaRequired reports a successful login that has no session.

mfaSetupConfirm() adopts credentials exactly as login() does, because it is the completion of a login (§25.2 rule 2) — including capturing the session's first CSRF token. mfaEnroll()/mfaConfirm() are the voluntary pair, from inside an existing session, and they do not clear the §17 decision memo — the subject has not changed, and discarding a warm memo on an unrelated profile action costs a round trip on every check that follows.

Both halves of an MfaEnrollment are Sensitive, and the second one matters: the otpauth:// URI contains the secret (§25.3). Wrapping the bare secret and then logging the URI leaks the same bytes.

Password reset, and the two things it will not tell you

requestPasswordReset() returns nothing and throws nothing on an unknown address, and this SDK exposes no way to tell the two cases apart. That is not an omission to improve on: a client that surfaced a "no such user" state — even one inferred from timing — would turn the endpoint into the account-enumeration oracle its uniform response exists to prevent. Likewise a 404 from passwordResetContext() means unknown, expired or already-consumed, and the SDK does not distinguish them either (§25.4 rule 3).

verifyEmail() and resendVerification() are unauthenticated — a user whose address is unverified may have no session at all — and carry the tenant as a body field, since §12.1 rule 2's ?tenant_id= convention is scoped to the /oauth2 endpoints.

Two resends, and why neither replaces the other (§25.7)

They look like one operation and are not. resendVerification() takes an address from an anonymous caller, so it must answer identically whether the address exists, is already verified, or is rate-limited — anything else is an oracle for which addresses have accounts. resendOwnVerification() is asked by a caller already signed in to the account it is asking about, so none of those outcomes discloses anything it did not bring with it, and this one tells the truth.

Neither is routed to the other, in either direction, and this SDK does not fall back from the authenticated one to the public one on a 409 or a 429: that fallback turns both failures back into a silent success and restores the exact bug §25.7 describes, with an extra round trip. resendOwnVerification() also takes no address parameter and sends no address field — a parameter here would let an authenticated session mail an arbitrary one.

Returning normally means the mail was enqueued, not delivered. Delivery is asynchronous and can still fail at the provider.

Worked end to end in examples/account_lifecycle.php.

Pushed Authorization Requests (CONTRACT.md §26, RFC 9126)

PAR moves the authorization request off the browser. Instead of putting scope, redirect_uri, state and the PKCE challenge into a URL the user agent carries, the client POSTs them straight to AXIAM over an authenticated back channel and puts an opaque request_uri in the redirect.

Three things worth knowing:

The push is not retried on a 5xx or a transport failure: it is a POST that creates server state, so it falls outside §16.2's read-only eligibility exactly as oidcExchange() does. The safe recovery is a fresh push, which costs one round trip and cannot double-consume anything. The requestUri is Sensitive because between the push and the redirect it is a bearer handle to a fully-formed authorization request (§26.5).

A FAPI 2.0 client has no alternative: profile: "fapi2" refuses a registration that does not set require_par, so such a client cannot authorize any other way (§21.1).

dpop_jkt — binding the code to a DPoP key at issue time (contract 1.42, RFC 9449 §10.1)

oidcPar() takes an optional sixth argument, dpopJkt: the base64url JWK SHA-256 thumbprint of the key the client will prove possession of at the token endpoint. Pushing it binds the authorization code to that key from the moment it is issued, rather than only when it is redeemed — which closes the window in which a stolen code can be redeemed by a different key.

The caller computes the thumbprint. CONTRACT.md §21.9 records this SDK as verifying DPoP proofs (Axiam\Sdk\Auth\DpopVerifier) but not generating them, so there is no client key here to derive one from; an application that holds one passes the same thumbprint it already computes for its own DPoP header, and the value is forwarded verbatim. Omitted from the form entirely when null or empty — §12.1 forbids transmitting an absent optional field as an empty value, and a server reading dpop_jkt= as a present-but-empty thumbprint would bind the code to nothing while making the request look key-bound.

request_uri is deliberately not exposed. Contract 1.42 added it to the server's PushedAuthorizationRequest schema, and RFC 9126 §2.1 makes it the one authorization parameter a client MUST NOT push — the server models it so it can refuse it. A client able to send it is a client able to chain one pushed request into another, which is the attack §26.2 rule 2 exists to prevent.

Worked end to end in examples/par_login.php.

Management API (Axiam\Sdk\Management, CONTRACT.md §27)

The administrative surface: 202 operations across 29 namespaces, generated from the vendored management-registry.json and openapi.json by scripts/gen_management.py and committed, so building this package needs no Python. CI re-runs the generator with --check on every PR, which is what stops the committed surface from drifting away from the contract it claims to implement.

The namespace handles sit directly on the client — $client->roles(), $client->serviceAccounts()->rotateSecret($id), the form §27.3's PHP row shows — and the same 29 handles are also reachable behind one accessor, $client->management() (§27.2 rule 4), which reads better where a call site is already dense with §1 methods. The two forms are equivalent: the direct accessors forward to management(), so rule 4's "where an SDK offers both, the two MUST return equivalent handles" holds structurally rather than by two code paths agreeing, and the suite asserts it by comparing the method, path and query each actually puts on the wire.

Searching a list (§27.4 rule 4). All twenty-six paginated operations take an optional free-text term, matched case-insensitively by the server against the identifying fields of whatever is being listed — a name or username, plus the record id, so a UUID pasted out of a log line finds its row.

The term lives on PageRequest rather than becoming a third argument on twenty-six generated methods, and that is what makes the walk above work at all: a per-method argument has nowhere to live between one request and the next, so a walk built on it would return the matches followed by the unfiltered tail.

null sends no search parameter. An empty or whitespace-only term is the same request — a search box that fires on every keystroke sends one the moment it is cleared, and "rows containing the empty string" is a different question from "all rows". The term is trimmed but never truncated: the server caps its length, and a client-side truncation the server would not have made is a silently different query the caller cannot see.

Enums are open (§27.11 rule 1). A value this SDK's copy of the spec does not list decodes to that enum's Unknown case rather than throwing. Throwing would fail the whole response, so one field of one record would take down the page it was on — including the records the caller did ask for. Unknown is never confused with a known case, and its wire spelling is the empty string, which no server value is: carrying an unrecognised value back into an update is refused by the server rather than written as a spelling it never used. A match over one of these enums needs an Unknown arm.

Certificate::$boundServiceAccountId is a projection, not a property: the server resolves it for a whole page in one query, so certificates()->listItems() populates it and certificates()->get($id) leaves it null. null there means "this read does not carry it", not "there is nothing bound" — the SDK does not issue a second request to fill it in, because a get that silently costs two round trips is the behaviour §27.4 rule 3 forbids for slug resolution, for the same reason (§27.11 rule 4).

Errors (§27.4 rule 7). Three statuses get a sub-type inside the §2 taxonomy, so a catch (AuthzError $e) written before §27 existed still behaves as it did:

status type parent why
404 NotFoundError AuthzError On a multi-tenant surface the server answers 404 for another tenant's object precisely so a probing caller cannot enumerate it. Re-drawing that line client-side would undo the protection.
409 ConflictError AuthzError §2 already maps 409 there; the sub-type keeps that mapping. getReasonCode() is the body's reason_code (the network operations always name one) — branch on it, never on the message.
400, 422 ValidationError NetworkError Inherited from §2's 400 row. Carries the server's per-field complaints.

Secrets (§27.5). A one-time secret is Sensitive: it prints and json_encodes as [SENSITIVE], so it cannot reach a log line by accident. The one writer that must send one in the clear unwraps it explicitly — ManagementTransport::encodeBody() walks the body and calls reveal(). PHP has no json_encode equivalent of Jackson's mixin or System.Text.Json's converter precedence, because JsonSerializable is consulted on the instance and nothing outranks it; making the unwrap explicit is better anyway, since there is no precedence rule to remember and exactly one greppable place where a secret is revealed.

The network namespace (§36, contract 1.62)

A tenant's network is described as segments (a VLAN and a Filter-Id envelope each, nodes of a reserved /network subtree) and, per segment, at most one reply profile (a typed record of the closed axiam-radius-reply/1 dictionary), plus the tenant's Session-Timeout cap. It is plain management CRUD — human-only, so a service-account token meets 401 — for an operator-run FreeRADIUS recipe. This SDK administers it; it never asks for a placement decision (POST /api/v1/network/decide is FreeRADIUS's, over mutual TLS, and has no method).

Declarative manifests (§27.6, §27.7)

Describe the tenant you want; let the SDK work out the difference.

Or as attributes, which is the idiom this SDK already uses for §11 and lets a tenant's shape live in version control as a type:

Four properties are worth knowing before you run one against production:

An incoherent manifest — a dangling reference, a cycle, a duplicate key — is refused before the first request, because discovering it halfway through an un-rollback-able apply is strictly worse.

See examples/management_basics.php, examples/management_manifest.php, examples/management_manifest_attributes.php, examples/network_manifest.php, and examples/device_mtls_provisioning.php — the last a full operator/device split that mints a Device certificate from the tenant's signing CA, binds it to a service account, writes the one-time private key at 0600, and then authenticates as the device over §6.1 mutual TLS with no password anywhere.

MCP resource-server helpers (Axiam\Sdk\Mcp, CONTRACT.md §28)

The resource-server half of the Model Context Protocol authorization handshake: publish the RFC 9728 document that tells an MCP client which authorization server guards this resource, and put the RFC 6750 WWW-Authenticate challenge on the 401 that starts its discovery.

AXIAM is the authorization server and implements none of this. Your MCP server is the resource server, and this is its side. Nothing here talks to AXIAM, performs any network I/O or touches the shared AxiamClient's own session — both operations are pure local computation, like oidcExchange's helpers and UmaChallenge::parse(). The client half — parsing a challenge, fetching a document, deciding whether to trust the authorization server it names — is deliberately not in the SDK: a helper that read a 401 and acted on it would send a credential to whatever host the 401 asked it to.

It is opt-in and off by default. With resourceMetadataUrl unset, AxiamMiddleware (Laravel) and AxiamAuthSubscriber (Symfony) behave byte-for-byte as they did before §28 existed: no header on any response, no status changed, no body changed, no path exempted.

The whole integration

On Symfony, the third step is a controller you wire into your own routing configuration rather than a macro-registered route — Symfony's routing table is declarative config the SDK cannot hook at runtime, which is also why the plan names this surface "subscriber + controller" rather than "subscriber + route":

A request with no credential now gets what it needs to go and get one:

and the document it points at answers without a credential:

The path is derived from the resource, not chosen. RFC 9728 §3.1 inserts /.well-known/oauth-protected-resource between the authority and the path, so https://mcp.example.com/mcp publishes at /.well-known/oauth-protected-resource/mcp and https://mcp.example.com at the bare well-known path. A trailing slash is carried through rather than trimmed — it is part of the identifier the client compares, and two resources that differ only by it are two resources. Exactly one route is registered per call; a deployment fronting several resources calls protectedResourceMetadata() once per resource.

You do not have to order the routes. Both AxiamMiddleware and AxiamAuthSubscriber exempt the document's path themselves, from the resourceMetadataUrl they were configured with — the guard checks the exact path on every request it sees, before it ever tries to extract a credential.

Announcing yourself obliges you to check

expectedAudience is mandatory once resourceMetadataUrl is set, and both guards refuse the configuration at construction, naming both options. A resource server that publishes "tokens for me carry this aud" and then does not check aud has published a claim it does not honour — and a token minted for a different MCP server opens it. That is the confusion RFC 8707 exists to prevent, so it is impossible to configure rather than merely discouraged:

With both set, a token carrying aud: "axiam:user" — a perfectly valid AXIAM token that simply was not minted for this resource — is a 401, exactly like a token minted for https://other.example.com/mcp.

The 403 that asks for a scope

One class of 403 carries a challenge, and only one: an AccessEnforcer configured with resourceMetadataUrl whose #[RequireAccess]/enforceAccess() call named a scope and whose decision came back allowed: false with reasonCode: "no_grant":

insufficient_scope is in the header and authorization_denied is in the body, and they are not two spellings of one thing: the body is the §11 error taxonomy, unchanged, and the header is the RFC 6750 hint. The scope named is the one the route asked for, verbatim — never synthesised, never derived from action/resource, never substituted from the document's scopes_supported, because where a deployment's AXIAM resource-scope names and its OAuth scope names differ, that mapping is the operator's decision and the SDK cannot see it.

Every other 403 carries no header at all: a require_access with no scope argument, a require_role failure, a CSRF refusal, and — the one that matters — a decision whose reasonCode is denied_by_rule. no_grant means ask for more, which is what a challenge invites a client to do; denied_by_rule means an administrator has already decided, and challenging on it would send an MCP client all the way around the authorization loop to arrive at the identical 403. An absent or unrecognised reasonCode is not eligible either.

Where a route also carries a §20.3 UMA challenge (a UmaChallenger configured on the same AccessEnforcer), the UMA challenge wins: it is per-route opt-in and carries a live ticket for the exact authority just refused, where this one is the generic hint. Only one WWW-Authenticate value is ever emitted.

The challenge says only what RFC 6750 can say

Expired, not yet valid, wrong tenant, wrong audience, bad signature, a cnf the guard could not satisfy, a sid in the §10.4 revocation feed — all of them are invalid_token, indistinguishably. This SDK's own guards never emit an error_description, and add nothing to the response that tells them apart. It is a 401 to an unauthenticated stranger: every distinction it draws is an oracle.

Mcp::bearerChallenge(...) exists for the challenge you build yourself, for your own 400, and it takes errorDescription for that reason alone. It refuses rather than escapes: RFC 6750 restricts every parameter to a character set that cannot contain " or \, so a value needing an escape is a value that does not belong in a challenge.

Validation refuses; it never repairs

Every §28.2 rule is checked by Mcp::protectedResourceMetadata() itself, and a violation throws Axiam\Sdk\Management\ValidationError (§2's taxonomy, unchanged — §28 adds no error type). Nothing is normalised, trimmed, lowercased or re-encoded to make it pass: that would publish a document describing a resource server that does not exist. The rules, in one list:

Member Rule
resource absolute URI with a scheme and an authority, no query and no fragment; a trailing slash is significant
any URL https, except on 127.0.0.1, [::1] or localhost — there is no flag, env var or debug build that widens this
authorizationServers at least one entry, each an issuer verbatim (no ?tenant_id=), no query, no fragment, no duplicates
scopesSupported RFC 6749 NQCHAR tokens, order preserved, no duplicates; an empty list omits the member
bearerMethodsSupported exactly ["header"] — this SDK's guards read a bearer credential from the Authorization header alone
resourceDocumentation an absolute URL, query and fragment permitted; omitted when absent, never null

Nothing in the document may come from a request. resource and authorizationServers are configuration, and this SDK offers no option to build either from the Host header, the Forwarded/X-Forwarded-* family or the request URL. A document assembled from the request is a document an attacker can point at an authorization server of their choosing — the whole handshake redirected with one header.

Nothing in §28 is wrapped in Sensitive<T> (§7), and that is a rule rather than an omission: the document is published unauthenticated to the world and the challenge goes to a caller who has just failed to authenticate, so both must stay readable. The corollary is the one that matters — no part of the presented credential reaches either of them, in any parameter, any header, any body or any log line the guard writes on the 401 path.

gRPC and AMQP

CONTRACT.md §28.5 rule 8 makes exposing bearerChallenge to a gRPC guard's error mapping optional ("MAY attach the same string as www-authenticate metadata on an UNAUTHENTICATED status") and forbids an AMQP equivalent outright ("no client waiting on a response to re-authorize with"). This SDK's Axiam\Sdk\Grpc namespace is a client for AXIAM's own gRPC services (checkAccess, getUserInfo) — the opposite direction from §28, which is about a guard protecting this application's own endpoints — so there is no gRPC (or AMQP) resource-server guard here to wire the challenge into. §10's guard, and therefore all of §28, is a REST-only surface on this SDK today.

RFC 7592 client configuration (CONTRACT.md §28.12)

A client that registered itself through POST /oauth2/register received a registration_client_uri and a registration_access_token, once. With them it manages its own registration — and only at this client's configured AXIAM: a URI at any other origin (or http unless the base URL is itself http on a loopback host) is refused with a ValidationError before a request is sent.

The token travels only as Authorization: Bearer, on a transport that carries nothing of this client's session (no cookie, no access token, no CSRF token) and follows no redirect. Neither write is retried — an update whose answer was lost has already rotated the token — and a 401 from these calls (an OAuthProtocolError with error === 'invalid_token') never triggers the §9 refresh. The read is retried per §16 on transport failures and 5xx/408/429 only.

Directory, SAML, SSF and SCIM targets (CONTRACT.md §29 – §32)

Four management namespaces, generated like the rest of §27, with the contract's call-site rules in each method's docblock.

ReadModifyWrite::ssfStream($stream, $changes) is the change-taking form of §32.2 (contract 1.62): it applies $changes to what you read and sends the events_requested and the expected_updated_at as read — the updated_at string byte for byte, and an [] as [] — and when $changes lowers events_allowed it cuts events_requested to the entries that are still allowed, in their order. An update that omits events_requested resets the stream to every allowed event, widening what the receiver narrowed ([] is the receiver's "none"; a list is stored as given and is 400 outside events_allowed) — updateStream()'s docblock says so beside the call, and a raw API client is bound by the same meaning. Called with no changes it is the plain converter, and cutting the requested list to a new ceiling is then the caller's duty, as is refreshing expected_updated_at: a write made since (the receiver's included) is a 409 and is never retried.

SamlIdpCredential has no key member and never will; a decoder meeting bind_secret, credential, authorization_header or private_key_pem in a response drops it. delete on a SCIM target deprovisions nothing downstream; retiring the active SAML credential with no successor stops SAML sign-on for the whole tenant. Every write in these namespaces is issued exactly once. A 400 is a ValidationError whose serverMessage carries the server's message (it names the rule — for a person; never parse it).

SSF receiver (CONTRACT.md §32.7)

For the relying party that receives AXIAM's CAEP and RISC events:

The verification order and the reason codes (SetFailureReason) are the contract's; alg is pinned to EdDSA before any key is looked up, and keys come only from the configured JWKS (never a jwk/x5c header). An unknown kid costs one forced JWKS refetch, at most once a minute. A JWKS fetch failure is a NetworkError, not a verdict on the SET, and it counts toward the same once-a-minute limit: for a minute after a failed fetch no SET triggers another, each getting a NetworkError instead (§34.2 P6). The key cache expires five minutes after the fetch that filled it, and the next SET fetches again. A verified SET is recorded: re-offered unacknowledged, it reads as replayed — so acknowledge what you processed. A replayed SET was accepted by this receiver earlier: poll returns it in $result->refused, and you acknowledge it in ack, not in setErrs (§34.2 P2) — the transmitter drops the event either way, and an error report would misinform it about an event you took. poll never keeps a jti it does not return (§34.2 P1): when a key fetch fails or the replay store cannot answer partway through a batch, the SETs already accepted are returned, and that SET is left unjudged — unrecorded, listed in $result->unjudged with the failure in $result->unjudgedCause, and neither acknowledged nor reported in setErrs, so the transmitter offers it again. The store is asked nothing more for that batch: a later SET that fails verification is still refused, and one that verifies is unjudged too. If nothing had been accepted yet, the failure is raised instead. A poll that returns with SETs unjudged emits the §19 event SsfUnjudgedEvent (ssf.poll, how many, and key_fetch or replay_store — no jti) to the client's telemetry hook, so an outage that raises nothing is still visible. The replay window defaults to, and may not be set below, seven days; the default store is in-memory and per-process, and unbounded in count (entries expire after the window) — behind PHP-FPM, pass a shared ReplayStore (an atomic SET NX EX in Redis, say). A store that cannot answer throws; it never answers "not seen" (§34.2 P4), and verifySet() raises the failure as a NetworkError with the store's exception chained as its cause (§2). malformed, invalid_type and replayed are answered as invalid_request, since only RFC 8935's codes go on the wire.

CIBA (CONTRACT.md §33)

Ask AXIAM to authenticate a user on another device, then collect the tokens. The client authenticates as it does at /oauth2/token — its oidcClientSecret, or, for a tls_client_auth client, its §6.1 certificate alone; a client with neither is refused locally.

Ping mode: initiate with delivery: CibaDeliveryMode::Ping, clientNotificationToken: new Sensitive($random). In the handler of your notification endpoint, call $client->cibaHandlePing($request->getHeaders(), (string) $request->getBody(), $token) — no I/O; it checks the bearer in constant time and returns the auth_req_id — answer 204, and only then $client->cibaPoll($authReqId) once. Fall back to cibaAwait() once half of expires_in has passed without a ping.

Signed requests (§33.2): a client registered with a request-signing algorithm passes signer: CibaRequestSigner::fromPem(CibaSigningAlg::EdDSA, new Sensitive($pem), 'kid-1'); the form then carries only client authentication and one request JWT. EdDSA (a PKCS#8 Ed25519 key) and ES256 (a P-256 key) are supported; PS256 is refused locally — firebase/php-jwt signs it only through phpseclib 3, which this SDK does not depend on.

A successful cibaInitiate proves nothing about the user: AXIAM answers an unknown or locked user exactly like a real one, and only expired_token says nobody answered. auth_req_id, the notification token and the signing key are Sensitive. A request is redeemed once — store the tokens cibaPoll/cibaAwait return before anything else.

TLS policy

Guzzle's verify option is always true (strict TLS, system trust roots) unless a customCa path (a PEM CA-bundle file path, never a boolean) is supplied to AxiamClient's constructor — the only escape hatch. There is no verify: false code path anywhere in this SDK's source, examples, or tests; CI enforces this with a dedicated grep gate (.github/workflows/sdk-ci-php.yml) that fails the build if any TLS-bypass pattern (other than the customCa exception) is ever introduced.

mTLS / client certificates (CONTRACT.md §6.1)

For IoT devices and service accounts that authenticate by mutual TLS, supply an X.509 client identity (signed by the tenant's organization CA) via the clientCert/clientKey constructor parameters — both PEM strings (clientCert is the certificate chain, clientKey its private key, PKCS#8 or PKCS#1):

The identity is applied to both transports of that client instance: the REST Guzzle clients (as cert/ssl_key) and any gRPC channel (via \Grpc\ChannelCredentials::createSsl(rootCerts, privateKey, certChain)). mTLS is opt-in; omitting it leaves the default bearer-cookie behavior unchanged. Presenting a client certificate is strictly additive — it never relaxes server verification, so the strict-TLS policy above still holds. clientCert and clientKey are all-or-nothing: supplying exactly one, or a non-PEM value, throws InvalidArgumentException at construction. The private key is secret material (§7): it is held behind Sensitive, written only to a short-lived 0600 temp file cURL reads, cleaned up when the client is destroyed, and never appears in any log, exception, or debug output.

RFC 8705 §5 mtls_endpoint_aliases (contract 1.40, CONTRACT.md §21.3 rule 2)

A TLS listener decides whether to ask for a client certificate during the handshake, before it has seen a byte of HTTP, so "request one on /oauth2/token but not on /oauth2/authorize" is not something a single listener can do. A deployment that wants both runs two — and mtls_endpoint_aliases in the discovery document is how the second one is named.

Once a client is built with clientCert, every request it makes presents that certificate, so the §12 helpers prefer the alias over the top-level entry of the same name wherever the document publishes one:

Operation Endpoint aliased
oidcExchange, oidcRefresh, loginClientCredentials, devicePoll, tokenExchange, umaExchangeTicket token_endpoint
introspect introspection_endpoint
revoke revocation_endpoint
deviceAuthorize device_authorization_endpoint
oidcPar pushed_authorization_request_endpoint

Three things this deliberately does not do:

A client built without clientCert keeps using the top-level endpoints even when the document publishes aliases: the alias exists for the handshake, and there is no handshake to make.

An unusable alias is refused, never fallen back from (§21.3.1 vector C, contract 1.43)

A published alias that cannot carry a client certificate throws an AuthError naming the member. It does not quietly fall back to the top-level endpoint.

Falling back looks like the safe answer and is the dangerous one. The caller asked to authenticate with a certificate; the operator published something unusable; presenting the certificate to the front-channel host authenticates nothing while appearing to work. A refusal is loud, local to one endpoint, and fixable by the operator who caused it.

Two defects, each a refusal on its own:

It is an AuthError rather than a NetworkError deliberately. Nothing failed in transport, and §16.3 retries NetworkError and only NetworkError — classifying this as one would attempt a permanent, deterministic misconfiguration three times and then report it as transient.

The check is scoped to the alias actually used, so a broken introspection_endpoint leaves the token endpoint working, and a client with no certificate never reads the member at all.

The session-revocation feed (CONTRACT.md §10.4, contract 1.44, opt-in)

JwksVerifier proves a token was issued by this deployment and has not expired. It cannot prove the session behind it still exists — so a logout, a role removal or an account disable does not reach a token already in a caller's hands until that token expires, up to fifteen minutes later. §10.2 records this, and its standing answer is to route the decision through gRPC introspection, which is correct and costs a round trip per request.

A deployment may instead publish GET /oauth2/revocations: the base64url-unpadded SHA-256 of every session id revoked within the last access-token lifetime. Polling it narrows the window to one poll interval, for one cacheable fetch per interval.

Five properties, each of which is a test in tests/RevocationFeedTest.php:

Rule What it means here
Default off The parameter is optional and defaults to null. Every existing call site keeps working and fetches nothing — asserted by counting requests on the wire, not by reading a flag.
Never on the request path verify() answers from the cached set and refreshes at most once per interval. A revoked session is rejected after one poll and not before.
Never fails closed Unreachable, non-200, unparseable, unknown alg, or more than MAX_ENTRIES entries — every one behaves exactly as no feed at all, and specifically not as an empty list, which would assert that nothing has been revoked. A failed poll leaves the last good set in place.
Only ever rejects Every §10.1 rule runs first and still decides. A token that fails one is rejected whatever the feed says, and the feed is not consulted — nor fetched — for it.
No sid, never matched A client-credentials token, an RPT or a token exchange has no session behind it. There is no jti fallback: hashing jti would match nothing while looking like it worked.

The poll interval defaults to 30 s and is clamped to a 15 s floor rather than refused, so a caller who asks for something faster gets the fastest thing on offer.

This is a narrowing, not a control. It shortens the window in which a revoked session is still accepted; it does not close it, and a deployment that does not publish the feed is unaffected.

Sensitive value redaction

Token-carrying values (access tokens, refresh tokens, MFA challenge tokens, and — per CONTRACT.md §12.5 — OIDC id_tokens, client_secrets, and PKCE code_verifiers) are wrapped in Axiam\Sdk\Core\Sensitive. Its __toString() and jsonSerialize() always return the literal string "[SENSITIVE]", and the wrapped value is stored in a private static WeakMap (not an instance property) so print_r()/var_export()/var_dump() cannot enumerate it either — call ->reveal() explicitly to obtain the real value. Errors that wrap a transport failure (NetworkError) redact Set-Cookie/Authorization/Cookie header values from the response before the exception object is ever constructed, so a raw token can never leak through a caught exception, a log line, or a JSON error body.

Examples

Testing

Runs the full PHPUnit suite: single-flight refresh concurrency (SC#2), Sensitive redaction (CR-04), AMQP HMAC verification, JWKS/EdDSA verification, the extension_loaded('grpc') REST-fallback guard, and both framework-bridge tests.

Regenerating the gRPC stubs

The protobuf message classes under src/Grpc/Gen/ are protoc output, generated from proto/axiam/v1/authorization.proto and proto/axiam/v1/userinfo.proto and committed to this repository — that is what lets composer require axiam/axiam-sdk work with no protobuf toolchain on your machine, and what keeps gRPC a suggest rather than a hard dependency. Unlike the other AXIAM SDKs, PHP does not use buf (D-03); it invokes protoc directly.

You only need this when proto/ changes:

The service clients (src/Grpc/AuthzGrpcClient.php and src/Grpc/UserInfoGrpcClient.php) are hand-written against \Grpc\BaseStub and are not generated — do not overwrite them.


All versions of axiam-sdk with dependencies

PHP Build Version
Package Version
Requires php Version >=8.2
ext-sodium Version *
guzzlehttp/guzzle Version ^7.16 || ^8.3
php-amqplib/php-amqplib Version ^3.7.5
firebase/php-jwt Version ^7.2
psr/log Version ^3.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package axiam/axiam-sdk contains the following files

Loading the files please wait ...