PHP SDK reference

revokegpt/revokegpt is the RevokeGPT server SDK for PHP 8.1 or later. It sends a response token to siteverify and applies every relying-party check: success must be true, the hostname (or app) and the action must match exactly, and the score must meet your threshold. It also wraps assessments, account protection, password and credential pair checks, payments and erase. The default transport is built on ext-curl; any PSR-18 client can be used instead. For a walkthrough, see the PHP quickstart.

Install

Not published yet

The revokegpt/revokegpt Composer package is not on its registry yet, so install it from a checkout of the repository as in the quickstart. After the first release the registry command applies.

composer config repositories.revokegpt path ./sdks/php   # from a checkout, until the first release
composer require "revokegpt/revokegpt:@dev"
composer require revokegpt/revokegpt                      # after the first release

Requirements: PHP 8.1+, ext-json. The default transport needs ext-curl; without it pass a PSR-18 client. The credential pair check needs ext-sodium (libsodium 1.0.18 or later) and ext-intl. Declare strict_types=1 in files that call the SDK.

Options

new Client(string $secret, string $endpoint, ?Options $options = null)
new Options(int $timeoutMs = 5000, ?ClientInterface $httpClient = null,
            ?RequestFactoryInterface $requestFactory = null, ?StreamFactoryInterface $streamFactory = null)

Option	Type	Default	Meaning
$secret	string	required	Your site’s secret key (rgsk_...). A management key (rgmk_...) throws \InvalidArgumentException.
$endpoint	string	required	The full siteverify URL. https:, or http: only on localhost or 127.0.0.1; no username, password, query or fragment. Must end in /siteverify for the assessment and password calls.
$timeoutMs	int	5000	1 to 60000. For the SDK’s own transport, a total deadline for one call. Nothing is retried.
$httpClient	PSR-18 ClientInterface	SDK curl transport	Your own client.
$requestFactory, $streamFactory	PSR-17 factories	defaults	Your own factories.

Methods

verify

public function verify(string $token, VerifyOptions $options): VerifyOutcome

new VerifyOptions(?string $expectedHostname = null, ?ExpectedApp $expectedApp = null, ?string $expectedAction = null,
                  ?float $minScore = null, ?string $remoteip = null, ?string $sitekey = null)

Parameter	Meaning
expectedHostname	Canonical: lowercase, no trailing dot, no port.
expectedApp	new ExpectedApp('android' | 'ios', $id), for tokens from the mobile SDKs.
expectedAction	Omit only if you use no actions; then a token that carries an action is refused.
minScore	A number from 0 to 1. Always pass it, or the outcome is threshold-missing.
remoteip, sitekey	Sent only when given and not empty; a given value is checked first.

Give exactly one of expectedHostname and expectedApp. Returns a VerifyOutcome with ok, reason (null only when ok is true) and result, a SiteverifyResult (verified, score, action, hostname, errorCodes, reasons, apkPackageName, iosBundleId). Gate on $outcome->ok alone.

use RevokeGPT\Client;
use RevokeGPT\VerifyOptions;

$client = new Client(getenv('REVOKEGPT_SECRET'), 'https://<api host>/v1/siteverify');

$outcome = $client->verify($token, new VerifyOptions(
    expectedHostname: 'shop.example',
    expectedAction: 'signup',
    minScore: 0.5,
    remoteip: $clientIp,
));
if (!$outcome->ok) {
    // refuse; $outcome->reason says why
}

createAssessment

public function createAssessment(AssessmentRequest $r): Assessment

Scores a token (or an IP address alone in express mode). Returns an Assessment with typed public properties and raw() for every field of the answer. An invalid token is still a 200 with tokenProperties->valid === false and score 0, so check valid.

annotate

public function annotate(string $nameOrAid, AnnotateInput $in = new AnnotateInput()): void

Reports what happened after an assessment. Annotate with ground truth you learn later, not guesses.

eraseAccount

public function eraseAccount(AccountRef $ref): void

Use one form of account id (accountId or hashedAccountId) everywhere you assess, annotate and erase.

isPasswordLeaked

public function isPasswordLeaked(string $password): PasswordCheckResult   // leaked, count

Hashes with SHA-1 locally and sends only the first 5 hex characters. A RevokeGPTError means the password was not checked: never treat it as “not leaked”. See password check.

checkCredentialPair

public function checkCredentialPair(string $username, string $password): CredentialPairResult   // leaked

Beta; while it is off the service answers feature-disabled (403). Without ext-sodium or ext-intl the call raises RevokeGPTError('feature-unavailable', 0) and sends nothing. A username with an unassigned Unicode code point throws \InvalidArgumentException with no request.

CardFields::from

RevokeGPT\Payments\CardFields::from(mixed $bin = null, mixed $last4 = null): array

Builds the only card fields a payment assessment accepts. Raises RevokeGPTError('bad-request', 0) for anything else.

Errors and failure model

verify never throws: every failure is an outcome. reason is one of invalid-expectation, invalid-options, invalid-token-format, network-error, http-error, not-verified, hostname-mismatch, app-mismatch, action-mismatch, score-missing, threshold-missing, score-below-threshold, score-invalid. Treat every reason as “do not accept”. A token is single use: after network-error or http-error it may already be spent, so a retry needs a new token. The full list is in errors.

A bad argument raises \InvalidArgumentException (or PHP’s \TypeError) before any request. Other calls throw RevokeGPTError:

Property	Meaning
$errorCode	For example unauthorized, feature-disabled, not-found, expired, rate-limited, bad-request, payload-too-large, unsupported-media-type, service-unavailable, network-error, invalid-response, feature-unavailable. Treat the set as open.
$status	The HTTP status (getCode() is the same); 0 when nothing was answered or no request was made.
$requestId	The service’s request id, when sent.
$retryAfterSeconds	Set for a 429 that carried Retry-After.

RevokeGPTUnavailable is the subclass for HTTP 503: “could not check”, never “clean”.

Configuration

The SDK reads no environment variables; the examples read the secret with getenv('REVOKEGPT_SECRET'). The SDK’s own transport (RevokeGPT\Http\CurlTransport) ignores http_proxy and the other proxy variables, never follows a redirect and always verifies TLS. To use a proxy or custom CA, inject your own PSR-18 client through Options. The SDK cannot interrupt your client, so set a total timeout and turn redirects off on it yourself, and give it no default credentials of its own. There is no async client.

Security notes

• The secret goes only in the POST body (siteverify) or the Authorization header, never in a URL, an exception, a log line, var_dump, serialize or json_encode.
• Never take expectedHostname from the request (the Host header): set it in configuration.
• Behind a proxy, take remoteip from your framework’s trusted-proxy setting, not from $_SERVER['REMOTE_ADDR'].
• No retries, and redirects are never followed.