System Connection Tokens¶

A SystemConnectionToken is a short-lived, single-use token that allows an e-commerce plugin or a consuming platform to finalize a SystemConnection from either side of the connection flow. Conflux issues a token with a fixed TTL, returns the plaintext value once to the caller, and thereafter stores only its SHA-256 hash. A token is consumed by setting used_at when the connection is finalized.

Model attributes¶

Attribute	Type	Notes
`id`	UUID	Primary key via `HasUuids`
`system_connection_id`	UUID (FK)	Owning `SystemConnection`; FK uses `restrictOnDelete`
`token`	string	SHA-256 hash of the plaintext token; unique; hidden from serialization
`expires_at`	datetime	Every token has a TTL; cast to `datetime`
`used_at`	datetime, nullable	Set when the token is consumed; `null` means not yet used; cast to `datetime`
`deleted_at`	timestamp	Soft deletes enabled

Token hashing¶

Conflux never stores the plaintext token. When a token is issued the plaintext is returned to the caller once and immediately discarded. Only the SHA-256 hash is persisted:

$hash = hash('sha256', $plaintext);

Lookups must hash the incoming value before querying:

SystemConnectionToken::where('token', hash('sha256', $incoming))->first();

Casts¶

Attribute	Cast
`expires_at`	`datetime`
`used_at`	`datetime`

Helper methods¶

`isExpired()`¶

Returns true when expires_at is in the past.

$token->isExpired(); // bool

`isUsed()`¶

Returns true when used_at is not null.

$token->isUsed(); // bool

`isValid()`¶

Returns true when the token is neither expired nor used. This is the single validity check to use before consuming a token.

$token->isValid(); // bool — equivalent to !isExpired() && !isUsed()

Pruning¶

Once a token is expired or consumed it serves no further purpose. The connection-tokens:prune Artisan command hard-deletes every token where expires_at is in the past or used_at is set, leaving only still-valid tokens untouched, and logs the number of records removed.

It is scheduled to run daily (registered in routes/console.php) and can also be run manually:

docker compose exec php php artisan connection-tokens:prune

Factory states¶

SystemConnectionTokenFactory ships three named states for use in tests:

State	Effect
`expired()`	Sets `expires_at` to one hour in the past
`used()`	Sets `used_at` to `now()`
`valid()`	Sets `expires_at` one hour ahead and `used_at` to `null` (default behaviour made explicit)

SystemConnectionToken::factory()->valid()->create();
SystemConnectionToken::factory()->expired()->create();
SystemConnectionToken::factory()->used()->create();

Source files¶

File	Purpose
`app/Models/SystemConnectionToken.php`	Eloquent model, casts, `isExpired`, `isUsed`, `isValid`
`app/Models/Concerns/BelongsToSystemConnection.php`	Shared `systemConnection(): BelongsTo` concern
`database/migrations/2026_06_26_092454_create_system_connection_tokens_table.php`	Table schema
`database/factories/SystemConnectionTokenFactory.php`	Factory with `expired`, `used`, `valid` states
`app/Console/Commands/PruneConnectionTokens.php`	`connection-tokens:prune` command — deletes expired or used tokens
`routes/console.php`	Daily schedule entry for the prune command