WalkPic documentation
Authentication
Your account approves the tool. Every request stays within that approval.
- Sign in to WalkPic. Use your first-party account at Manage integrations. The CLI and MCP do not perform an Apple/email sign-in themselves.
- Approve a personal grant. Choose WalkPic CLI for SDK/CLI use or WalkPic MCP for the local stdio server. Select read scopes and a grant lifetime of 1, 7 or 30 days.
- Receive credentials once. An opaque
wp_int.access token lasts 10 minutes. A separate refresh credential supports explicit rotation within the approved grant lifetime. - Launch the tool through a trusted host. The host supplies
WALKPIC_BASE_URL=https://walkpic.comandWALKPIC_ACCESS_TOKENin the process environment. Keep token values out of command arguments, request JSON, committed configuration and model context.
What a grant can read
| Scope | Access |
|---|---|
publications:read | Read an accessible publication and its access state |
library:owned:read | List your published walks |
library:received:read | List walks and authors shared with you |
saved:read | List your saved walks |
explore:read | Browse accessible public walks |
places:read | Read accessible place visits |
A grant does not make private content public or bypass sharing rules. The server checks the current grant, client, scope, account and resource access. Expiry, revocation and access loss are enforced on the server.
Refresh and revoke
Refresh is explicit, not automatic. It rotates the credential pair and cannot extend the selected scopes or grant expiry. The SDK uses a separate refresh credential session; the CLI delivers the validated pair through a trusted private local pipe descriptor. MCP has no credential-management tools: restart its child process with the newly delivered access token.
If a refresh acknowledgement is lost, do not reuse the old refresh credential. Revoke the grant in Manage integrations and approve a new one. You can revoke a grant there at any time.
Other authentication types
The API reference also includes first-party bearer sessions, deletion receipts, unlisted-publication links and live-writer capabilities. These are separate mechanisms; CLI/MCP do not accept them instead of a personal integration grant. MeshAgent room/project credentials are not WalkPic user credentials.
Storage and protocol
The SDK keeps explicitly supplied credentials in memory and aborts old requests when they rotate or close. CLI/MCP environment configuration is ephemeral; it is not a Keychain or persisted secure-store integration. Local stdio MCP is supported; remote MCP OAuth and device-login flows are not implemented.