--- title: "auth.md — pjespjes.com agent access" description: "Authentication and safe read-only agent access for the pjespjes.com catalog API." canonical: "https://pjespjes.com/auth.md" --- # auth.md — pjespjes.com agent access pjespjes.com supports agent access for read-only product discovery, Kosovo PC-part price comparison, offer lookup, compatibility-oriented build research, and citation retrieval. ## Audience This document is for autonomous or assisted AI agents, agent hosts, and other software acting for a user who wants to search the public pjespjes.com catalog. It is not a checkout, ordering, or retailer-account integration. x402, when enabled, charges for API data access only; it does not process retailer checkout or card payments. ## Discovery - Resource server: https://pjespjes.com/agent-api/v1 - Human-readable agent documentation: https://pjespjes.com/agents - Protected Resource Metadata: https://pjespjes.com/.well-known/oauth-protected-resource/agent-api/v1 - REST API: https://pjespjes.com/agent-api/v1 - Curated builds: https://pjespjes.com/agent-api/v1/builds - OpenAPI document: https://pjespjes.com/agent-api/v1/openapi.json - MCP endpoint: https://pjespjes.com/mcp - Authentication challenge endpoint: https://pjespjes.com/agent/auth - OAuth 2.0 Authorization Server Metadata: https://pjespjes.com/.well-known/oauth-authorization-server - OAuth 2.0 token endpoint: https://pjespjes.com/oauth/token The service supports the OAuth 2.0 client-credentials grant for the catalog.read scope. A client id and secret must be provisioned by the operator; anonymous read-only access remains available without OAuth. When x402 is enabled, catalog data routes first return HTTP 402 with payment requirements; retry with the PAYMENT-SIGNATURE header after an agent-native payment. The API-key flow below remains available for operator-issued credentials. ## Registration and provisioning There is no public self-service API-key registration or token-minting endpoint in this application. Anonymous read-only access is available. An agent that needs an operator-issued bearer API key should submit a request through the contact page: - Provisioning page (GET): https://pjespjes.com/contact - Provisioning request endpoint (POST): https://pjespjes.com/api/mail - Agent registration discovery endpoint: https://pjespjes.com/oauth/register - Direct support email: contact@pjespjes.com The contact endpoint accepts a JSON contact message; it only sends a provisioning request to the operator and does not return a credential. Do not put an API key, password, or other secret in the contact message. If approved, the operator creates the key and delivers it out of band. - One-request auth challenge: GET https://pjespjes.com/agent/auth returns HTTP 401 with the WWW-Authenticate header set to Bearer resource_metadata="https://pjespjes.com/.well-known/oauth-protected-resource/agent-api/v1". Anonymous read-only catalog requests remain supported at the REST endpoints above. The following machine-readable manifest describes that manual provisioning method. It is informational service metadata, not OAuth Authorization Server metadata: ```json { "agent_auth": { "skill": "https://pjespjes.com/auth.md", "register_uri": "https://pjespjes.com/oauth/register", "claim_uri": "https://pjespjes.com/oauth/register", "identity_endpoint": "https://pjespjes.com/oauth/register", "identity_types_supported": [ "anonymous" ], "anonymous": { "credential_types_supported": [ "bearer_api_key" ], "claim_uri": "https://pjespjes.com/oauth/register" }, "credential_types_supported": [ "bearer_api_key" ], "registration_methods": [ { "id": "operator_issued_bearer_api_key", "type": "manual_provisioning", "provisioning_uri": "https://pjespjes.com/contact", "request": { "method": "POST", "uri": "https://pjespjes.com/api/mail", "content_type": "application/json", "fields": [ "name", "email", "subject", "message" ] }, "credential": { "type": "bearer_api_key", "transport": "authorization_header", "format": "Bearer ", "delivery": "out_of_band" } } ] } } ``` ## Supported authentication methods ### Anonymous read-only access Call the documented GET endpoints without an Authorization header. Anonymous requests are rate limited and remain read-only. This is the default method for public catalog discovery. ### Operator-issued bearer API key When a key has been provisioned, send it only over HTTPS in the HTTP Authorization header: ```http Authorization: Bearer ``` The key is for the read-only agent API and MCP surface. Never place it in a URL, query parameter, prompt, catalog citation, or client-visible page. Treat it as a secret, rotate or revoke it by contacting the operator, and stop using it if it is reported lost or compromised. The `catalog.read` scope names the read-only capability; the current operator-issued key format is not an OAuth access token and is not exchanged at a token endpoint. ### OAuth 2.0 client credentials Use the discovered token endpoint https://pjespjes.com/oauth/token with a provisioned client id and secret. The endpoint accepts HTTP Basic authentication or client_id/client_secret form fields and returns a short-lived Bearer access token for the catalog.read scope. Do not send the client secret to catalog routes. ```http POST /oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&scope=catalog.read ``` Use the returned access_token as `Authorization: Bearer `. The token is accepted by the REST and Streamable HTTP MCP surfaces and expires in the `expires_in` interval. ## Not currently supported pjespjes.com does not support OpenID Connect identity assertions, ID-JAG identity assertions, verified-email registration assertions, or anonymous claim ceremonies for this agent surface. OAuth 2.0 is limited to machine-to-machine catalog access; it is not a user-login or checkout flow. ## Usage Use the returned canonical pjespjes.com product or offer URL when citing results. Prices and availability are snapshots from the latest published catalog release and can change at the retailer; verify the retailer page before purchase. The catalog compares participating Kosovo stores and is not a complete inventory of every retailer in Kosovo.