Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Service-to-service authentication via Bearer tokens — scoped, revocable, and audited.

Machine Identity

Bearer credentials for service-to-service traffic

Machine authentication is stateless, scope-aware, and easy to revoke without touching browser sessions.

# Reference format only — this demo page does not validate tokens.
# Real verification lives in the semitexa/api package.
curl -H "Authorization: Bearer demo-client-id:demo-secret-key-abc123" \
  https://your-app.com/api/products

Property	Value
Status on this page	`Reference only — tokens are not verified here`
Real verifier	`semitexa/api machine-auth pipeline`
Format	`Bearer {client_id}:{secret}`
Handler priority	`50 (runs before session auth)`
Scopes	`Stored on MachineCredential, checked per route`
Revocation	`Set revoked_at for immediate effect`
Audit	`Credential ID + timestamp logged per request`

MachineAuthHandler Bearer {id}:{secret} MachineCredential scopes revocation

Verified against Semitexa Ultimate 2026.09.19.1020

Machine Auth

Service-to-service authentication via Bearer tokens — scoped, revocable, and audited.

How it works

Clients send an Authorization: Bearer {client_id}:{secret} header. MachineAuthHandler in semitexa/api reads that header from the live request, splits the token once into id and secret, and verifies it against the MachineCredential store without persisting the raw secret. Secret verification delegates to MachineCredential::verifySecret() (password_verify() under the hood), successful auth updates only usage audit fields such as lastUsedAt and requestCount, and the resolved MachinePrincipal exposes credential identity and scopes without echoing the secret back into application state.

Why this matters

Machine-to-machine auth needs a different shape than session auth: no redirect flow, no cookies, explicit scope boundaries, and an audit trail. A revoked credential takes effect immediately without restarting the server because the check happens at request time against the live credential record.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Auth;67use App\Application\Payload\Api\ProductListPayload;8use App\Application\Resource\Api\ProductListResource;9use App\Domain\Api\ProductApiReaderInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: ProductListPayload::class, resource: ProductListResource::class)]15final class MachineAuthHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected ProductApiReaderInterface $reader;1920    public function handle(ProductListPayload $payload, ProductListResource $resource): ProductListResource21    {22        return $resource->fromProducts($this->reader->listForApi());23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Auth;

use App\Application\Payload\Api\ProductListPayload;
use App\Application\Resource\Api\ProductListResource;
use App\Domain\Api\ProductApiReaderInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ProductListPayload::class, resource: ProductListResource::class)]
final class MachineAuthHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected ProductApiReaderInterface $reader;

    public function handle(ProductListPayload $payload, ProductListResource $resource): ProductListResource
    {
        return $resource->fromProducts($this->reader->listForApi());
    }
}