AXIAM PHP SDK

__construct()

Parameters

$baseUrl : string

The AXIAM server's base URL (e.g. https://api.axiam.example).

$tenant : string

The tenant slug — REQUIRED, no nullable default anywhere on this signature (D-13, §5). There is no default tenant; constructing this client without one is a compile-time (missing required argument) error, and an empty string is rejected at runtime as a backstop.

$orgSlug : string|null = null

Organization slug — mutually exclusive with $orgId. The real login/refresh handlers require an org identifier beyond CONTRACT.md §5's tenant-only minimum (mirrors the Python/C# sibling SDKs' org_slug/org_id constructor options).

$orgId : string|null = null

Organization UUID — mutually exclusive with $orgSlug.

$customCa : string|null = null

A CA bundle FILE PATH (PEM-encoded) — the ONLY TLS escape hatch (§6/D-12). Never pass a value here to disable TLS verification; there is no such option on this class.

$clientCert : string|null = null

§6.1 (mTLS): the client's X.509 identity certificate CHAIN as a PEM STRING (not a path). When supplied together with $clientKey, this client presents that certificate for mutual TLS on both the REST and gRPC transports. Purely additive — server verification is never relaxed (§6.1.2). Must be a PEM value; a non-PEM string is rejected at construction. null (default) leaves the default bearer-cookie behavior unchanged (§6.1.5).

$clientKey : string|null = null

§6.1/§7 (mTLS): the PEM STRING of the private key matching $clientCert (PKCS#8 or PKCS#1). Secret material — it is held behind Sensitive and never logged, displayed, or exposed via a getter. $clientCert and $clientKey are all-or-nothing: supplying exactly one throws InvalidArgumentException.

$logger : LoggerInterface|null = null

Injectable logger (D-15: diagnostic-only — status codes and operation names, NEVER a token/credential value). Defaults to a silent NullLogger.

$restOnly : bool|null = null

Force REST-only authz transport. null (default) resolves to true when $grpcTarget is not supplied (there would be nothing to connect the gRPC transport to) and false otherwise — an explicit true/false always wins. REST authz ALWAYS works regardless of this setting (D-03).

$cacheTtlSeconds : int = 300

JwksVerifier's local JWKS TTL cache lifetime.

$grpcTarget : string|null = null

gRPC target host:port (e.g. api.axiam.example:9443), required only to actually use the gRPC authz transport.

$transportHandler : callable|null = null

Test-only seam (NOT part of the public API contract, trailing/optional so it never affects SC#1's "tenant is required" reflection check): a raw Guzzle handler (e.g. GuzzleHttp\Handler\MockHandler) used as the base handler for both internal HandlerStacks instead of Guzzle's default cURL/stream handler. Mirrors the C# sibling SDK's CreateForTesting internal seam, adapted to Guzzle's own documented HandlerStack::create($mockHandler) testing idiom (docs.guzzlephp.org/en/stable/testing.html) — never used by production code.

$oidcClientId : string|null = null

CONTRACT.md §12: the relying party's OAuth2 client_id, used by every oidc*/introspect/revoke operation and matched against an ID token's aud/azp (§12.4 rule 4). Required only by callers that use the §12 OIDC/SSO helpers — omitting it leaves the §1–§11 surface completely unaffected, and a §12 call without one raises AuthError before any wire call.

$oidcClientSecret : Sensitive|string|null = null

CONTRACT.md §12: the confidential client's client_secret, held behind Sensitive (§12.5). Omit for a public client — introspect/revoke/loginClientCredentials REQUIRE it (§12.1 note 4) and raise AuthError when it is absent; oidcExchange/ oidcRefresh omit it from the form body entirely when absent, per §12.1's "MUST omit rather than send empty/null" rule.

$oidcTenantId : string|null = null

CONTRACT.md §12.3 rule 4: the tenant UUID used as the default ?tenant_id= query parameter on /oauth2/* calls when a call does not supply one explicitly. $tenant above is a SLUG (§5's X-Tenant-ID header value) and is never accepted where the wire contract requires a UUID — a §12 call with neither this nor a per-call tenantId raises AuthError client-side, with no wire call.

$expectedIssuer : string|null = null

CONTRACT.md §10.1 rule 5: the iss value local token verification requires. CONDITIONAL and unset by default — null means no issuer check is performed at all; once supplied, a token whose iss differs (or which carries no iss) is rejected. There is no default value and no hardcoded AXIAM issuer anywhere in this SDK.

$expectedAudience : string|null = null

CONTRACT.md §10.1 rule 6: the aud value local token verification requires. CONDITIONAL and unset by default — null means no audience check at all; once supplied, a token whose aud does not contain it (including one with no aud) is rejected. An app guarding a user-facing resource server should generally expect axiam:user; it is not defaulted, because a service-to-service guard legitimately expects a different audience.

$retryEnabled : bool = true

$decisionMemoTtlMs : float = 0.0

$telemetryHook : callable|null = null

$actingTenant : string|null = null

CONTRACT.md §5.2 rule 1 (contract 1.51): the construction-time form of the acting-tenant switch — the tenant UUID this client acts on from its very first request, sent as X-Axiam-Tenant on every /api/v1 request while set. Meaningful only for an organization-level* principal (§5.2); nothing is gated here — construction precedes the login that would reveal whether the principal really is one, and a service account never receives a login result at all — only the value's shape (a UUID) is checked. null (the default) sends no such header, byte- for-byte what every client sent before 1.51. Distinct from $tenant above (§5 rule 2's X-Tenant-ID, sent unconditionally and never read by the server as a tenant switch). See self::actingTenant() for the on-client form and its gating.

__destruct()

§6.1: cleans up the `0600` temp files backing the client-certificate identity when this client is destroyed, so no PEM material (least of all the private key) outlives the object on disk. A no-op when mTLS was not configured.

actingTenant()

Switches this client to act on `$tenantId` — CONTRACT.md §5.2 rule 1 (contract 1.51). Every subsequent `/api/v1` request this client makes carries `X-Axiam-Tenant: $tenantId`, until {@see self::clearActingTenant()} is called or another `actingTenant()` replaces it.

Parameters

$tenantId : string

Tags

throws

NetworkError

if $tenantId is not a UUID. The server silently ignores an X-Axiam-Tenant value that does not parse and answers for the caller's own tenant instead — reporting success about the wrong tenant — so this is refused client-side, with no wire call.

AuthzError

when this client holds a login result (§5.2.2) that reported organizationLevel: false (an ordinary tenant principal is a principal of exactly one tenant, and the server answers 403 to anything else), or that reported reachableTenantIds not containing $tenantId (§5.2.3 rule 4). A client holding no such result — a service account from client credentials or the device login, an injected token, a session completed without a user object — has nothing to gate on: the header is sent as asked, and the server's 403 is the answer. An organization-level service account is a supported design, and the server honours the header for one on the same terms as for a user.

actingTenantId()

The tenant this client currently acts on, or `null` when it acts on its own tenant.

audit()

Append-only audit log, read-only by construction.

authenticateDevice()

`authenticateDevice` — `POST /api/v1/auth/device` (CONTRACT.md §6.1 rules 6-10, contract 1.51): the mTLS device login. The client presents the X.509 identity certificate configured via `$clientCert`/`$clientKey`, and the server authenticates it, no request body, no tenant/credential needed beforehand.

batchCheck()

`batchCheck` — results preserve input order (CONTRACT.md §1).

Parameters

$checks : array<int, array{action: string, resourceId: string, scope?: string|null}>

caCertificates()

Organization CAs and the per-tenant signing CAs chained beneath them.

can()

`can` — the browser/UI-scenario alias for {@see self::checkAccess()} (CONTRACT.md §1 note). Argument order is `(action, resource)` — matching {@see self::checkAccess()} and every other AXIAM SDK's `can`/`Can` (D-09/SDK-Q09; this was previously reversed relative to the rest of the SDK family).

Parameters

$action : string

$resource : string

certificates()

End-entity X.509 certificates -- the ones issued to users, services and IoT devices.

checkAccess()

`checkAccess` — delegates to {@see AuthzDispatcher} (REST default, gRPC when available).

Parameters

$action : string

$resourceId : string

$scope : string|null = null

$subjectId : string|null = null

Additive, optional (CONTRACT.md §11.2.2 — declarative authorization helpers): when given, the check is evaluated for THIS subject (a UUID) rather than whichever identity this client's own session represents. This matters for a framework bridge sharing ONE AxiamClient instance (typically authenticated as a service account, or not authenticated at all) to authorize each inbound HTTP request's OWN end user: passing subjectId: $endUserId here checks the end user's permissions, never the shared client's. null (the default) preserves this method's pre-§11 behavior exactly.

checkAccessDecision()

`checkAccess`, returning the **full** decision including CONTRACT.md §11 rule 9's `reason_code` — see {@see \Axiam\Sdk\Rest\AccessDecision}'s own docblock for why that distinction matters. Delegates to {@see AuthzDispatcher} on whichever transport {@see self::checkAccess()} itself would use (REST default, gRPC when available), so the two never disagree about which transport ran.

Parameters

$action : string

$resourceId : string

$scope : string|null = null

$subjectId : string|null = null

See self::checkAccess()'s own docblock.

cibaAwait()

Poll for a CIBA request's outcome until it is decided or expires, honouring `interval` and `slow_down` (CONTRACT.md §33.7). Returns the token set without adopting it. See {@see OidcEngine::cibaAwait()}, including the ping-mode fallback.

Parameters

$initiated : CibaInitiateResponse

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

$clock : CibaClock|null = null

The clock to wait on (tests).

cibaHandlePing()

Verify a CIBA ping's bearer and return the `auth_req_id` it names (CONTRACT.md §33.1) — pure, no I/O. Answer the ping, then {@see self::cibaPoll()}. See {@see OidcEngine::cibaHandlePing()}.

Parameters

$headers : array<string|int, string|array<int, string>>

The ping request's headers.

$body : string

$expectedToken : Sensitive

Tags

throws

AuthError

when the Authorization header is not exactly the expected bearer.

ValidationError

when the body is not a ping body.

cibaInitiate()

`POST /oauth2/bc-authorize` (CONTRACT.md §33.1) — ask AXIAM to authenticate a user on another device. **Never retried**, and a success proves nothing about the user; see {@see OidcEngine::cibaInitiate()}.

Parameters

$request : CibaInitiateRequest

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

$clock : CibaClock|null = null

Stamps the response's receivedAt (tests).

Tags

throws

AuthError

locally, for a client with no credential or a server without CIBA.

OAuthProtocolError

for the server's refusals.

cibaPoll()

One CIBA token request (CONTRACT.md §33.1). `access_denied` and `expired_token` are {@see \Axiam\Sdk\Core\OAuthProtocolError}s told apart by `isAccessDenied()` / `isExpiredToken()`. **Store the tokens first**: a request is redeemed once. See {@see OidcEngine::cibaPoll()}.

Parameters

$authReqId : Sensitive

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

clearActingTenant()

Stops acting on another tenant: no further request sends `X-Axiam-Tenant`, and this client acts on its own tenant again (CONTRACT.md §5.2 rule 1's "a way to clear it").

close()

Releases this client's local resources (CONTRACT.md §18).

confirmPasswordReset()

`POST /api/v1/auth/reset/confirm` (CONTRACT.md §25.1) — set the new password.

Parameters

$confirmation : PasswordResetConfirmation

debugClientCertOptions()

Test-only seam (not part of the public API contract, mirroring {@see self::debugVerifyOption()}): exposes the §6.1 client-identity options (`cert` = certificate-chain file, `ssl_key` = private-key file) actually configured on this client's authz Guzzle transport, so tests can assert the mTLS wiring without performing a live TLS handshake. Both entries are `null` when mTLS was not configured. The values are FILE PATHS, never the PEM bytes — this seam never surfaces the private key itself.

debugVerifyOption()

deleteClientRegistration()

`DELETE registration_client_uri` (RFC 7592 §2.3, CONTRACT.md §28.12) — delete this client's registration. A `204` returns normally.

Parameters

$registrationClientUri : string

$registrationAccessToken : Sensitive

Tags

throws

ValidationError

for a URI at another origin (local).

OAuthProtocolError

for an answer carrying error.

deviceAuthorize()

`POST /oauth2/device_authorization` (CONTRACT.md §14.1) — start the device grant and obtain the code pair.

Parameters

$scope : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when the discovery document advertises no device_authorization_endpoint.

deviceLogin()

The composed §14.3 helper: start the grant, hand the caller the user code (before the first poll), poll to completion.

Parameters

$onUserCode : callable(DeviceAuthorization): void

Invoked before the first poll.

$scope : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

$adoptAsCredential : bool = false

$sleep : callable(int): void|null = null

Injectable sleeper, for tests.

$now : callable(): float|null = null

Injectable clock in seconds, for tests.

$retrySleep : callable(float): void|null = null

Injectable sleeper (milliseconds) for the §16 waits inside a poll.

devicePoll()

`POST /oauth2/token` with the device-code grant (CONTRACT.md §14.1) — **one** poll attempt, for an application driving its own loop. Most callers want {@see self::deviceLogin()}.

Parameters

$deviceCode : Sensitive|string

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

directory()

A tenant's LDAP / Active Directory identity source (CONTRACT §30): its configuration, account linking, and the sync job's status.

emailConfig()

Transactional-mail transport, configurable at organization level and overridable per tenant.

expectedAudience()

The `$expectedAudience` this client was constructed with (CONTRACT.md §10.1 rule 6), or `null` when no audience check is configured.

federation()

Upstream IdP configuration and the per-user links it produces.

getUserInfo()

`getUserInfo` — the gRPC-ONLY OIDC-style userinfo operation (CONTRACT.md §1.1, contract 1.3): returns the authenticated caller's identity claims from `axiam.v1.UserInfoService/GetUserInfo`, the low-latency counterpart of the server's REST `GET /oauth2/userinfo`. Delegates to {@see AuthzDispatcher} — this class never hand-rolls the gRPC transport (D-03).

groups()

Named collections of users. Roles assigned to a group are inherited by every member.

introspect()

`POST /oauth2/introspect` (RFC 7662, CONTRACT.md §12.1) — ask the server whether a token is active and, if so, for its metadata. Requires confidential-client credentials (§12.1 note 4). A `401` here is a client-credential failure surfaced as {@see \Axiam\Sdk\Core\OAuthProtocolError} and NEVER enters the §9 refresh guard (§12.3 rule 3).

Parameters

$token : Sensitive|string

The token to introspect — accepts the wrapped or bare form.

$tokenTypeHint : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when no oidcClientSecret was configured.

introspectToken()

`introspectToken` — `axiam.v1.TokenService/IntrospectToken` (CONTRACT.md §1.1.1/§10.3, contract 1.51). The RFC 7662 set, plus the confirmation. See {@see self::validateToken()} for the shared rules this method follows exactly; the only difference is the richer RFC-7662-shaped return value.

Parameters

$inspectedAccessToken : Sensitive|string

login()

`POST /api/v1/auth/login` (CONTRACT.md §1). Returns a typed {@see LoginResult} — an MFA challenge (HTTP 202) is an expected outcome, not an exception: callers MUST check {@see LoginResult::$mfaRequired} before assuming a session was established (SC#1).

Parameters

$email : string

$password : string

loginClientCredentials()

`POST /oauth2/token` with `grant_type=client_credentials` (CONTRACT.md §12.1) — service-account machine-to-machine login. Requests no `openid` scope, so the response carries no `id_token`. Pass `$adoptAsCredential: true` to additionally adopt the returned access token as this client's bearer credential for subsequent same-origin REST calls (§12.1, an opt-in MAY) — the token is held behind {@see Sensitive} inside {@see Session} and is NEVER sent to `/oauth2/*`.

Parameters

$scope : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

$adoptAsCredential : bool = false

Tags

throws

AuthError

when no oidcClientSecret was configured — this grant cannot be performed by a public client (§12.1 note 4).

loginOpaque()

`POST /api/v1/auth/opaque/login/start` followed by `/finish` — OPAQUE login, RFC 9807 (CONTRACT.md §23).

Parameters

$usernameOrEmail : string

$password : string

Tags

throws

NetworkError

if the tenant has OPAQUE disabled (the endpoint answers 404 — a property of the tenant, not of any user), if ext-ffi or libaxiam_opaque_ffi is absent, or if the server names a key-stretching function this SDK cannot ask for. Deliberately not AuthError: reporting a configuration gap as a credential failure would send a user off to reset a password that works, and would stop a caller falling back to self::login()

AuthError

for a wrong password, an account that does not exist, and a server that does not hold the record — indistinguishable by design. Nothing is sent to login/finish in that case (§23.4 rule 7). Raised under mode: "required" and under a response with no mode; under "optional" the exchange is retried over self::login() first and this carries that call's failure instead

logout()

`POST /api/v1/auth/logout` (CONTRACT.md §1) and clears local session state: the shared cookie jar (§4) and the captured CSRF token (§3). The session id comes from the current access token's `jti` claim (unverified decode — an operational hint only, never an authorization decision, mirroring the Python/C# sibling SDKs).

logoutUrl()

Build the RP-initiated logout URL to redirect the user agent to (CONTRACT.md §12.7.2). Does **not** clear this client's own session.

Parameters

$idToken : Sensitive|string

$postLogoutRedirectUri : string|null = null

$state : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when the discovery document advertises no end_session_endpoint.

management()

The CONTRACT.md §27 management surface: 190 operations across 28 namespaces.

mfaConfirm()

`POST /api/v1/auth/mfa/confirm` (CONTRACT.md §25.1) — activate the factor {@see self::mfaEnroll()} offered. Returns whether MFA is now enabled.

Parameters

$totpCode : string

mfaEnroll()

`POST /api/v1/auth/mfa/enroll` (CONTRACT.md §25.1) — start voluntary TOTP enrolment for the signed-in user.

mfaSetupConfirm()

`POST /api/v1/auth/mfa/setup/confirm` (CONTRACT.md §25.1) — finish forced enrolment and, with it, the login that was interrupted.

Parameters

$setupToken : Sensitive|string

$totpCode : string

mfaSetupEnroll()

`POST /api/v1/auth/mfa/setup/enroll` (CONTRACT.md §25.1) — start the enrolment a {@see self::login()} demanded.

Parameters

$setupToken : Sensitive|string

network()

A tenant's network segments and the RADIUS reply profile each owns, and the tenant's `Session-Timeout` cap (CONTRACT §36, contract 1.62). Every write is conditional on the `version` the caller read; the decision route FreeRADIUS calls is not SDK surface.

notificationRules()

Which events raise a notification, and to whom.

oauth2Clients()

Registered OAuth2/OIDC clients -- the registration half of what §12, §21 and §26 then speak to.

oidcBegin()

Build an authorization request (CONTRACT.md §12.1) — **pure local computation, no network I/O**. Generates a `state`/`nonce` (CSPRNG, ≥128 bits) and a fresh PKCE verifier/challenge pair (**S256 only**), and builds `$configuration`'s `authorization_endpoint` into a redirect URL with exactly the eight SDK-owned query parameters plus any `$extraParams` supplied.

Parameters

$configuration : OidcConfiguration

$redirectUri : string

$scope : string|array<int, string>|null = null

openid is added automatically when absent (§12.1 rule 4). Defaults to openid.

$extraParams : array<string, string> = []

Extra authorization-request parameters (e.g. prompt, login_hint). Throws InvalidArgumentException if one tries to override an SDK-owned parameter (§12.1 rule 5).

oidcDiscover()

`GET /.well-known/openid-configuration` (CONTRACT.md §12.1) — fetch the OIDC discovery document, cached per origin with a ≥5-minute TTL and single-flight de-duplication of concurrent callers (§12.3 rule 6). The document's own `issuer` is authoritative for ID-token validation (§12.4 rule 3) and may legitimately differ from `$baseUrl` behind a proxy — never treated as an error (§12.3 rule 6).

oidcExchange()

`POST /oauth2/token` with `grant_type=authorization_code` (CONTRACT.md §12.1) — exchange an authorization code for a token set, validating the returned ID token in full (§12.4) before returning. `$nonce` is MANDATORY: this grant always requests `openid`, so §12.4 rule 6 always applies. On ANY §12.4 failure the whole token set is discarded and {@see AuthError} is raised with the matching reason code (§12.4 rule 7) — `getReason()` returns one of `invalid_alg`, `unknown_kid`, `invalid_signature`, `invalid_issuer`, `invalid_audience`, `token_expired`, `nonce_mismatch`.

Parameters

$code : string

$codeVerifier : Sensitive|string

The verifier from the matching AuthorizationRequest — accepts the wrapped or bare form.

$redirectUri : string

$nonce : string

$tenantId : string|null = null

Tenant UUID for the required ?tenant_id= query parameter (§12.3 rule 4). Falls back to the client's oidcTenantId.

$configuration : OidcConfiguration|null = null

A pre-fetched discovery document, to avoid re-reading the (cached) one. Fetched via self::oidcDiscover() when omitted.

oidcPar()

`POST /oauth2/par` (CONTRACT.md §26.1) — push the authorization request over the back channel and get an opaque handle to redirect with.

Parameters

$request : AuthorizationRequest

$redirectUri : string

$configuration : OidcConfiguration|null = null

$scope : string|array<int, string>|null = null

$tenantId : string|null = null

$dpopJkt : string|null = null

RFC 9449 §10.1 dpop_jkt — the caller-computed JWK SHA-256 thumbprint of the DPoP key, pushed so the authorization code is bound to that key at issue time. Omitted from the form when null. This SDK verifies DPoP proofs but does not generate them (CONTRACT.md §21.9), so the thumbprint comes from the application, not from here.

oidcRefresh()

`POST /oauth2/token` with `grant_type=refresh_token` (CONTRACT.md §12.1) — refresh an {@see OidcTokenSet} under the SAME §9 single-flight guard {@see self::refresh()} uses. A **distinct operation** from {@see self::refresh()} (the cookie/opaque-token session path) — the two are never merged, aliased, or fall back to one another, but they share ONE guard slot: a concurrent `oidcRefresh()` call finding the guard busy with a cookie-session refresh retries (bounded) rather than returning a stale token set.

Parameters

$refreshToken : Sensitive|string

The refresh token to redeem — accepts the wrapped or bare form.

$scope : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

opaqueAvailable()

Whether this installation can perform OPAQUE (§23.2).

opaqueEnrollment()

Builds a registration record for `$password`, to send with any request that sets one: `POST /api/v1/users`, `/auth/password/change`, `/auth/reset/confirm` and `/admin/bootstrap`.

Parameters

$password : string

Tags

throws

NetworkError

if the tenant has OPAQUE disabled, if ext-ffi or libaxiam_opaque_ffi is absent, or if the server names a key-stretching function this SDK cannot ask for

opaqueEnrollmentForSelf()

Builds a registration record for the **caller's own** new password, sealed against the tenant the caller's account lives in.

Parameters

$password : string

Tags

throws

NetworkError

when no login has completed on this client yet — the principal tenant is reported by the login response, so there is nothing to seal against before then — and on the same terms as self::opaqueEnrollment() otherwise.

organizations()

Organizations an SDK client may read and configure. Creation and deletion are outside the SDK boundary (§27.0).

passwordResetContext()

`GET /api/v1/auth/reset/context` (CONTRACT.md §25.1) — the OPAQUE policy for the account a reset token belongs to.

Parameters

$token : Sensitive|string

permissions()

Permissions -- an action on a resource, optionally narrowed by a scope.

pgpKeys()

OpenPGP keys used for audit signing and encrypted data export.

platform()

Deployment-level probes and FIDO metadata state. Unauthenticated where the server leaves them so.

privacy()

GDPR self-service: the authenticated account's own export and erasure. Scoped to the caller, never to another user.

reactors()

Registration of §22 AMQP extension actors -- the admin surface §22.9 describes, which no SDK could previously reach.

readClientRegistration()

`GET registration_client_uri` (RFC 7592 §2.1, CONTRACT.md §28.12) — read this client's own registration, as a client that registered itself through `POST /oauth2/register` (RFC 7591).

Parameters

$registrationClientUri : string

$registrationAccessToken : Sensitive

Tags

throws

ValidationError

for a URI at another origin — local, with no request sent.

OAuthProtocolError

for an answer carrying error, at any status: 401 invalid_token is an unknown client, a wrong or rotated-away token, another tenant's client or a client with no token — the server never says which — and it never refreshes this client's session (§28.12.2 rule 3).

refresh()

`POST /api/v1/auth/refresh` (CONTRACT.md §1), routed through {@see Session}'s single-flight guard (§9, D-06) — the SAME mechanism {@see RefreshMiddleware} triggers reactively on a `401`. A failure surfaces as {@see AuthError} with no retry (§9.3).

requestPasswordReset()

`POST /api/v1/auth/reset` (CONTRACT.md §25.1) — ask for a reset mail.

Parameters

$request : PasswordResetRequest

resendOwnVerification()

`POST /api/v1/users/me/resend-verification` (CONTRACT.md §25.1, §25.7) — resend the **signed-in caller's own** verification mail, and say what happened.

Tags

throws

AuthError

when there is no session — raised client-side, with no wire call.

AuthzError

on the 409: already verified, or an account state that must not be sent a live token.

NetworkError

on the 429: the daily resend limit is reached.

resendVerification()

`POST /api/v1/auth/resend-verification` (CONTRACT.md §25.1) — the **unauthenticated** resend, for a caller with no session.

Parameters

$email : string

$tenantId : string

resolvedOrgId()

The organization UUID §27 routes substitute for `{org_id}`, or `null` when the client was constructed without one (§27.4 rule 3).

resolvedTenantId()

The tenant UUID §27 routes substitute for `{tenant_id}`, or `null` when the client was constructed without one (§27.4 rule 3).

resources()

The resource hierarchy role assignments cascade down.

revoke()

`POST /oauth2/revoke` (RFC 7009, CONTRACT.md §12.1) — revoke an access or refresh token. Returns nothing. Per RFC 7009 the server answers `200` for an unknown, expired, or already-revoked token too, so this call is **idempotent**: only a `401` (client authentication failed) is an error, surfaced as {@see \Axiam\Sdk\Core\OAuthProtocolError} (§12.1 note 5). A `5xx` still raises {@see NetworkError}.

Parameters

$token : Sensitive|string

The token to revoke — accepts the wrapped or bare form.

$tokenTypeHint : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when no oidcClientSecret was configured.

roles()

Roles, their permission sets, and their assignment to users and groups.

saml()

A tenant's SAML 2.0 identity provider (CONTRACT §29): service providers, SP-metadata import, and the IdP signing-credential lifecycle.

scimTargets()

A tenant's outbound SCIM targets (CONTRACT §31): the downstream SCIM 2.0 service providers AXIAM pushes users and groups to.

scimTokens()

Bearer tokens for the SCIM 2.0 provisioning endpoint.

scopes()

Sub-resource granularity, always addressed under their resource.

serviceAccounts()

Machine identities, their secrets, and the certificate a device-bound one authenticates with.

settings()

Effective settings, and the organization/tenant layers they resolve from.

ssf()

A tenant's Shared Signals Framework streams (CONTRACT §32): which receiver gets which CAEP and RISC security events.

ssfReceiver()

An SSF receiver — the helper a relying party uses to verify the Security Event Tokens AXIAM pushes to it and to poll a poll stream (CONTRACT.md §32.7). See {@see \Axiam\Sdk\Ssf\SsfReceiver::verifySet()} and {@see \Axiam\Sdk\Ssf\SsfReceiver::poll()}.

Parameters

$issuer : string

The transmitter's issuer — the tenant's issuer, e.g. https://iam.example/t/{tenant_id} — compared with iss exactly.

$audience : string

This receiver's audience: the stream's audience.

$jwksUri : string|null = null

The JWKS (AXIAM: {issuer}/oauth2/jwks); exactly one of this and $discoveryUrl.

$discoveryUrl : string|null = null

The SSF configuration document; its jwks_uri is used and its issuer must be $issuer.

$accessTokenProvider : callable(): Array|null = null

The bearer poll() presents: a client-credentials token carrying ssf.manage. null for push only.

$replayWindowSeconds : int = SsfReceiver::MIN_REPLAY_WINDOW_SECONDS

At least, and by default, seven days.

$replayStore : ReplayStore|null = null

Shared store for several processes; in-memory when omitted.

Tags

throws

ValidationError

locally, for a replay window under seven days, an empty issuer or audience, or not exactly one key source.

ssoComplete()

`POST /api/v1/auth/federation/oidc/callback` (CONTRACT.md §12.1) — step 2 of upstream SSO: consumes the single-use `$state`, provisions or links the user, and establishes the session. The session arrives as `Set-Cookie` — not in the response body (§12.1 note 6) — so it is captured automatically via this client's shared §4 cookie jar; the freshly-issued §3 CSRF token is captured too, exactly as {@see self::login()} does. §12.4 does not apply here: no ID token ever reaches the SDK on the federation path.

Parameters

$state : string

$code : string

ssoCompleteHandoff()

`POST /api/v1/auth/federation/handoff` (CONTRACT.md §12.1, contract 1.38) — redeem the single-use `axiam_handoff` code the SAML and Apple flows deliver.

Parameters

$code : string

ssoCompleteOauth2()

`POST /api/v1/auth/federation/oauth2/callback` (CONTRACT.md §12.1, contract 1.38) — step 2 of a plain-OAuth2 login. Same `Set-Cookie` session and same §3 CSRF capture as {@see self::ssoComplete()}. §12.4 does not apply: an `OAuth2` provider issues no ID token at all (§12.1 note 11).

Parameters

$state : string

$code : string

ssoProviders()

`GET /api/v1/auth/federation/providers` (CONTRACT.md §12.1, contract 1.38) — which "Sign in with X" buttons to render for a workspace. The identifiers travel as **query** parameters; this is a `GET` and sends no body.

Parameters

$orgId : string|null = null

$orgSlug : string|null = null

$tenantId : string|null = null

$tenantSlug : string|null = null

ssoStart()

`POST /api/v1/auth/federation/oidc/start` (CONTRACT.md §12.1) — step 1 of first-time SSO against an **upstream** IdP. No JWT required. One tenant form (`$tenantId`/`$tenantSlug`) and one org form (`$orgId`/`$orgSlug`) must be resolvable, from the arguments or from this client's construction options (§5.1) — an unresolvable one raises {@see AuthError} client-side, with no wire call. Redirect the browser to the returned `authorizeUrl` and round-trip `state` back into {@see self::ssoComplete()} unmodified; the server keeps the nonce to itself (§12.1 note 7).

Parameters

$federationConfigId : string

$redirectUri : string

$tenantId : string|null = null

$tenantSlug : string|null = null

$orgId : string|null = null

$orgSlug : string|null = null

ssoStartOauth2()

`POST /api/v1/auth/federation/oauth2/start` (CONTRACT.md §12.1, contract 1.38) — step 1 of a login through a **plain-OAuth2** upstream (GitHub, Facebook, `generic_oauth2`). Call this, rather than {@see self::ssoStart()}, exactly when the provider's `protocol` is `OAuth2` (§12.1 note 10).

Parameters

$federationConfigId : string

$redirectUri : string

$tenantId : string|null = null

$tenantSlug : string|null = null

$orgId : string|null = null

$orgSlug : string|null = null

tenants()

Tenants within an organization -- the isolation boundary every other namespace is scoped to.

tokenExchange()

`POST /oauth2/token` with the RFC 8693 grant (CONTRACT.md §15.1) — exchange a token for a **narrower** one.

Parameters

$subjectToken : Sensitive|string

$subjectTokenType : string

What kind of token $subjectToken is. Required (§15.1): OidcClient::ACCESS_TOKEN_TYPE for an AXIAM access token, or OidcClient::JWT_TOKEN_TYPE for a trusted external issuer's JWT (§15.7). Never inferred from the token.

$actorToken : Sensitive|string|null = null

$scopes : array<int, string>|null = null

$audience : string|null = null

$resource : string|null = null

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when no oidcClientSecret was configured.

umaChallengeHeader()

Format a `WWW-Authenticate: UMA` header (CONTRACT.md §20.3, emit half).

Parameters

$realm : string

$asUri : string

$ticket : Sensitive|string

umaDeleteResource()

`DELETE /uma2/rreg/resource_set/{id}` (CONTRACT.md §20.1).

Parameters

$pat : Sensitive|string

$id : string

umaExchangeTicket()

The UMA ticket grant (CONTRACT.md §20.1) — redeem a permission ticket for an RPT.

Parameters

$ticket : Sensitive|string

$claimToken : Sensitive|string

$tenantId : string|null = null

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

when no oidcClientSecret was configured.

umaListResources()

`GET /uma2/rreg/resource_set` (CONTRACT.md §20.1) — the ids this client registered.

Parameters

$pat : Sensitive|string

umaParseChallenge()

Parse a `WWW-Authenticate: UMA …` header (CONTRACT.md §20.3) — local computation, and deliberately **no** exchange of the ticket it finds.

Parameters

$header : string

umaReadResource()

`GET /uma2/rreg/resource_set/{id}` (CONTRACT.md §20.1).

Parameters

$pat : Sensitive|string

$id : string

umaRegisterResource()

`POST /uma2/rreg/resource_set` (CONTRACT.md §20.1) — register a UMA resource set.

Parameters

$pat : Sensitive|string

A client-credentials token carrying uma_protection (§20.2 rule 1) — never this client's session token.

$name : string

$type : string|null = null

$resourceScopes : array<int, string> = []

umaRequestTicket()

`POST /uma2/perm` (CONTRACT.md §20.1) — mint a permission ticket.

Parameters

$pat : Sensitive|string

$permissions : array<int, RequestedPermission>

umaUpdateResource()

`PUT /uma2/rreg/resource_set/{id}` (CONTRACT.md §20.1) — replace a resource set.

Parameters

$pat : Sensitive|string

$id : string

$name : string

$type : string|null = null

$resourceScopes : array<int, string> = []

updateClientRegistration()

`PUT registration_client_uri` (RFC 7592 §2.2, CONTRACT.md §28.12) — **replace** this client's registration, and receive a **rotated** registration access token.

Parameters

$registrationClientUri : string

$registrationAccessToken : Sensitive

$metadata : ClientRegistration

Tags

throws

ValidationError

for a URI at another origin (local).

OAuthProtocolError

for invalid_client_metadata, invalid_redirect_uri, invalid_request or invalid_token; a refusal does not rotate the token.

users()

Users within the client's tenant, and the administrative side of their second factor and lockout state.

validateToken()

`validateToken` — `axiam.v1.TokenService/ValidateToken` (CONTRACT.md §1.1.1/§10.3, contract 1.51). Signature + expiry, plus the confirmation (`cnf`) a resource server validating over gRPC needs in order not to accept a sender-constrained token as a bearer token (§10.1 rule 9).

Parameters

$inspectedAccessToken : Sensitive|string

verifyEmail()

`POST /api/v1/auth/verify-email` (CONTRACT.md §25.1).

Parameters

$token : Sensitive|string

$tenantId : string

verifyLocally()

Verify an INBOUND caller's token and nothing else — the seam every request guard must use (CONTRACT.md §10.1 rule 8). Delegates straight to {@see JwksVerifier::verify()}, which applies the full §10.1 minimum local-verification set INCLUDING rule 9 (contract 1.51), and returns `null` on any failure with **no fallback to another credential**.

Parameters

$token : string

$tenant : string

verifyLocallyOrFallback()

Local-first JWT verification with a reactive-refresh fallback (D-02) — for the SDK's own OUTBOUND calls, where the token being verified is this client's own and refreshing it is the intended recovery. Tries {@see JwksVerifier::verify()} first (no network call on the happy path); if that fails (expired/unknown-kid/invalid token), attempts the shared single-flight refresh (§9, D-06) and re-verifies the FRESH access token. Returns `null` — never unverified claims — on any failure.

Parameters

$token : string

$tenant : string

verifyLogoutToken()

Verify a back-channel logout token the OP pushed to this application's `backchannel_logout_uri` (CONTRACT.md §12.7.3).

Parameters

$logoutToken : string

$configuration : OidcConfiguration|null = null

Tags

throws

AuthError

on any failed check.

verifyMfa()

`POST /api/v1/auth/mfa/verify` (CONTRACT.md §1) — completes the two-phase flow started by {@see self::login()} when {@see LoginResult::$mfaRequired} was `true`. `$challengeToken` is the `Sensitive`-wrapped value from that `LoginResult` (D-11: never a raw string on the public surface).

Parameters

$challengeToken : Sensitive

$totpCode : string

verifyWithProofs()

{@see self::verifyLocally()}, applying CONTRACT.md §10.1 rule 9 against `$proofs` — evidence YOUR connection established for THIS request, never a value taken from a caller-settable request header (§10.1 rule 9 detail 2: e.g.

Parameters

$token : string

$tenant : string

$proofs : PresentedProofs

webauthnAuthenticateFinish()

`POST /api/v1/auth/webauthn/authenticate/finish` (CONTRACT.md §24.1).

Parameters

$stateToken : Sensitive|string

$response : string

webauthnAuthenticateStart()

`POST /api/v1/auth/webauthn/authenticate/start` (CONTRACT.md §24.1) — begin the **second-factor** ceremony.

Parameters

$challengeToken : Sensitive|string

webauthnDiscoverableFinish()

`POST /api/v1/auth/webauthn/authenticate/discoverable/finish` (CONTRACT.md §24.1).

Parameters

$stateToken : Sensitive|string

$response : string

webauthnDiscoverableStart()

`POST /api/v1/auth/webauthn/authenticate/discoverable/start` (CONTRACT.md §24.1) — begin the usernameless ceremony.

Parameters

$workspace : WebauthnWorkspace|null = null

webauthnPolicy()

Per-tenant attestation policy governing the §24 ceremonies, and the compliance report over it.

webauthnRegisterFinish()

`POST /api/v1/auth/webauthn/register/finish` (CONTRACT.md §24.1) — hand the authenticator's answer back and store the credential.

Parameters

$stateToken : Sensitive|string

$credentialName : string

$response : string

webauthnRegisterStart()

`POST /api/v1/auth/webauthn/register/start` (CONTRACT.md §24.1) — begin enrolling a passkey for the signed-in user.

webauthnSetupRegisterFinish()

`POST /api/v1/auth/webauthn/setup/register/finish` (CONTRACT.md §24.1, contract 1.45) — finish enrolling the passkey or security key {@see self::webauthnSetupRegisterStart()} offered, and with it the login that was interrupted.

Parameters

$setupToken : Sensitive|string

$stateToken : Sensitive|string

$credentialName : string

$response : string

webauthnSetupRegisterStart()

`POST /api/v1/auth/webauthn/setup/register/start` (CONTRACT.md §24.1, contract 1.45) — begin enrolling a passkey or security key as the FIRST factor of a forced login enrolment.

Parameters

$setupToken : Sensitive|string

webhooks()

Outbound event notifications. Delivery signatures are verified with the §13 helper, which this namespace configures.