# Spaaza API Live Access Use this skill when the user wants to "talk" to the Spaaza API in natural language. ## Security first - Security is critical. - Usernames, passwords, and OTP codes must be used only for the active session. - Do not store secrets in files, long-term notes, or commits. - Ask for explicit user consent before production changes. Use user-facing reassurance: - "I will only use your credentials for this session and I will not store them anywhere permanent." ## Optional local session cache - By default, the agent should store issued session information in a user-local cache outside any repository so future sessions can reuse it until expiry. - This cache should contain only minimal session data, such as: - `environment` - `api_base_url` - `session_user_id` - `session_key` - `session_expires_date` - `saved_at` - Recommended locations are: - macOS/Linux: `~/spaaza/sessions/` - Windows: `%USERPROFILE%\spaaza\sessions\` - Use separate files per environment, for example `test01.json` and `prod.json`. - Where possible, use restrictive permissions for the directory and files. - Never store usernames, passwords, or OTP codes in this cache. - On first use, create this cache in the user's home directory. - At the start of a session, first ask whether the user already has an active session or has used this skill before for the target environment. - If cached session reuse is enabled, load only the file for the chosen environment and reuse it only when the session has not expired and matches the requested environment. - If the cache is missing, expired, rejected, or no longer matches the intended environment, perform a fresh login. - After a fresh login, write or replace the environment-specific cache file. ## Environment mapping The API base URL differs per environment. Spaaza provides the appropriate `{API hostname}` during onboarding: - `test01` (staging): `https://{API hostname}` (staging) - `prod` (production): `https://{API hostname}` (production) Default to `test01` unless production is explicitly requested. ## Environment prompt behavior At the start of live API tasks, ask the user which environment to use: - "Do you want me to connect to staging/testing (`test01`) or production (`prod`)?" If user does not specify, recommend `test01` first. ## Documentation usage Always read the matching documentation before making calls when request shape/headers are uncertain. Switch docs hostname based on environment: - `test01` -> `https://docs-test01.spaaza.com` - `prod` -> `https://docs.spaaza.com` The documentation site should be treated as the source for endpoint coverage. The endpoint list is updated often. Before creating login requests, read the login endpoint documentation first. Before consuming other endpoints, read the relevant endpoint documentation first. If a page is missing on one docs host, check the equivalent page on the other docs host before guessing. ## Public request-building resources Use these public resources together: - Spaaza API docs: `https://docs.spaaza.com` - Spaaza POSTMAN collection: `https://github.com/Spaaza/SPAAZA.postman` - Resources API schema endpoint: `GET /resources/schema` The POSTMAN collection is a cloneable public repository that provides: - request names and endpoint grouping, - prepared headers and parameter examples, - sample JSON and form payloads, - a broader request catalogue for building task-specific endpoint shortlists. When you need a fuller endpoint catalogue for a task, use the POSTMAN collection, the documentation site, and the Resources API schema together: - use the POSTMAN collection to discover likely requests and draft request structure, - use the documentation site to confirm public endpoint behavior and authentication requirements, - use the Resources API schema to confirm resource names, filters, and field shapes for resource-oriented requests. If the POSTMAN collection and documentation appear to differ, trust the documentation first and then verify against live responses. ## POSTMAN collection workflow At the start of a live API task, ask: - "Do you already have a local clone of the Spaaza POSTMAN collection? If yes, share the path. If not, I can use the public repo URL or help you clone it." If the user already has a local clone: - inspect the collection there before drafting requests, - use it as a local request catalogue for the current session, - ask whether the agent may remember that path in a user-local config for future sessions. If the user does not have a local clone: - offer to use the public repo directly as the reference source, - or offer to clone `https://github.com/Spaaza/SPAAZA.postman` into a user-approved local directory for side-by-side use with this skill. ## Optional local POSTMAN collection memory - If the user explicitly opts in, the agent may remember the local clone path of the Spaaza POSTMAN collection in a user-local config outside any repository. - This config should contain only: - `repo_url` - `local_path` - `saved_at` - `last_validated_at` - Recommended locations are: - macOS/Linux: `~/spaaza/config/postman-collection.json` - Windows: `%USERPROFILE%\spaaza\config\postman-collection.json` - On each run, if this file exists and the stored path still exists, offer to reuse it. - If the stored path is no longer valid or the user wants a different clone, ask permission before updating the remembered path. - Never store credentials, OTP codes, session keys, or any other auth material in this file. ## Implicit trigger handling If intent implies live API work (for example "check campaigns", "update this campaign", "retrieve chain info") offer to use this skill even if the user did not name it. When multiple inputs are missing, ask for them once in a single checklist-style block rather than repeating the same request in the same message. The opening message should contain exactly one intro, one checklist of missing essentials, and at most one short security note. Ask only for missing essentials: - whether the user already has an active session or has used this skill before for the target environment, - environment, - action scope (endpoint + identifiers), - credentials only when needed, - OTP only after login step 1 returns a session passcode key. - optional local POSTMAN collection clone path only when helpful for request discovery. - After the first reply, recover as much context as possible from cached session and remembered POSTMAN metadata before asking further questions. ## Admin login flow (2FA) 1. `POST /auth/login` 2. prompt user for OTP 3. `POST /auth/session` with `session_passcode` + `session_passcode_key` 4. save the issued session information in the environment-specific home-directory cache file 5. retrieve the admin user's chain permissions before chain-scoped work 6. use `X-Spaaza-Session-User-Id` and `X-Spaaza-Session-Key` on authenticated calls If the OTP expires, restart from `POST /auth/login`. ## Endpoint catalogue (documented examples) - `POST /auth/login` - docs: `https://docs.spaaza.com/api/login/` - `POST /auth/session` - docs: `https://docs.spaaza.com/api/session/` - `GET /internal/get-campaigns` - docs: `https://docs.spaaza.com/api/get-campaigns/` - `GET /internal/get-campaign` - docs: `https://docs.spaaza.com/api/get-campaign/` - `POST /auth/get-basket-price` - docs: `https://docs.spaaza.com/api/get-basket-price/` - `POST /auth/add-basket` - docs: `https://docs.spaaza.com/api/add-basket/` - `GET /internal/get-user` - docs: `https://docs.spaaza.com/api/get-user/` - `GET /internal/get-businesses` - docs: `https://docs.spaaza.com/api/get-businesses/` - `GET /internal/get-vouchers` - docs: `https://docs.spaaza.com/api/get-vouchers/` ## Permission requests If runtime restrictions prevent required actions, ask clearly before escalating: - "I need permission to perform this action. Do you want to allow it?" ## Request handling guidance - Include `X-Spaaza-API-version` on requests. - Default to `X-Spaaza-API-version: 1.6.3` unless the relevant endpoint documentation says a different version should be used. - Where possible, include a `User-Agent` header. - After login, retrieve the admin user's permitted chains before chain-specific reads or mutations. - For non-trivial live work, build a short endpoint shortlist from the POSTMAN collection and the documentation before making requests. - For changes such as `alter-*`, `add-*`, or `delete-*`, run a follow-up `get-*` request to verify the result. - When values from one authenticated request must feed into later requests, prefer a JSON-aware wrapper around `curl` or an equivalent approach that reduces quoting and parsing mistakes. ## Session cleanup - Clear temporary variables after the task where possible. - Do not echo credentials back unless explicitly asked. - Keep final reports focused on outcomes rather than secret material.