# Sparkoo auth.md

You are an agent discovering how to use **Sparkoo** (https://sparkoobd.com), a Bangladesh educational-toys storefront.

Sparkoo does **not** implement OAuth/OIDC agent registration (no ID-JAG, claim ceremony, or `/agent/auth` endpoints). This document is the source of truth for what agents can do today.

## Audience

- Catalog and shopping assistants that need product, shipping, and checkout context
- Integrations that call public storefront HTTP APIs
- Systems that sign outbound HTTP requests as Sparkoo (Web Bot Auth)

## Step 1 — Discover public APIs (no registration)

Most agent work uses **public** endpoints. No client registration or access token is required.

| Resource | URL |
| --- | --- |
| API catalog (RFC 9727) | https://sparkoobd.com/.well-known/api-catalog |
| OpenAPI | https://sparkoobd.com/openapi.json |
| Human API docs | https://sparkoobd.com/docs/api |
| Saleor GraphQL | https://api.sparkoobd.com/graphql/ |
| Health | https://sparkoobd.com/api/health |
| BD thanas | https://sparkoobd.com/api/bd/thanas?district=Dhaka |
| Content Signals | https://sparkoobd.com/robots.txt |
| Web Bot Auth JWKS | https://sparkoobd.com/.well-known/http-message-signatures-directory |

GraphQL channel slug: `sparkoobd`. Currency: BDT.

Prefer `Accept: text/markdown` on HTML pages when you want a markdown representation of storefront content.

## Step 2 — Public GraphQL usage

POST JSON to https://api.sparkoobd.com/graphql/ with a GraphQL `query` (and optional `variables`). Catalog, collections, and guest checkout queries work without credentials.

Do **not** invent OAuth client credentials or scrape the human login form for automated account creation.

## Step 3 — Customer account credentials (humans / assisted flows)

Protected account operations (orders, profile, saved addresses) require a **Saleor customer JWT**:

1. Human (or human-in-the-loop) completes phone or email OTP via GraphQL `otpRequestLogin` / `otpVerifyLogin`.
2. The storefront stores access + refresh tokens in HttpOnly cookies; API callers may send `Authorization: Bearer <access_token>`.
3. Refresh with Saleor `tokenRefresh` when the access token expires (~5 minutes).

There is **no** programmatic agent registration endpoint that mints customer tokens without OTP. Agents must not bypass OTP or harvest SMS codes.

Login UI for humans: https://sparkoobd.com/login

## Step 4 — Outbound identity (Web Bot Auth)

When **Sparkoo** sends bot/agent HTTP requests to other sites, receivers can verify signatures using:

- Directory: https://sparkoobd.com/.well-known/http-message-signatures-directory
- Content-Type: `application/http-message-signatures-directory+json`

This identifies Sparkoo as a signing agent; it is **not** a way for third-party agents to obtain Sparkoo API credentials.

## Not supported (yet)

- `/.well-known/oauth-protected-resource` OAuth PRM for agent registration
- `/.well-known/oauth-authorization-server` with an `agent_auth` block
- `register_uri` / `POST /agent/identity` / ID-JAG / verified-email claim flows
- Client-credentials or API keys for third-party agents

If you need machine access beyond public catalog APIs, contact Sparkoo via https://sparkoobd.com/contact — do not assume OAuth agent registration exists.

## Credential use summary

| Need | Method |
| --- | --- |
| Read catalog / health / thanas | No auth |
| Act as a customer (account APIs) | Saleor Bearer JWT after OTP |
| Prove Sparkoo as request signer | Web Bot Auth (outbound only) |