# Inflo Share

Inflo Share is a developer platform for embedding sharing, SSO/OIDC, and
data-collaboration primitives. AI agents and CLIs can manage developer apps
on a user's behalf using Personal Access Tokens (Bearer infpat_...).

## Two hosts, two jobs

- https://infloapp.com      → developer/business API (PATs, app registration,
                      /api/v1/*). Does NOT host end-user OIDC sign-in.
- https://sso.infloapp.com    → OIDC issuer for end-user sign-in
                      (authorization_code, id_token, userinfo).

When configuring an OIDC client library such as openid-client, set the
issuer to the SSO host, not the API host. Hitting the API host's
/.well-known/openid-configuration 302-redirects to the SSO host as a
safety net for misconfigured clients.

  Discovery:    https://sso.infloapp.com/.well-known/openid-configuration
  JWKS:         https://sso.infloapp.com/.well-known/jwks.json
  Authorize:    https://sso.infloapp.com/oauth/authorize
  Token:        https://sso.infloapp.com/oauth/token
  Userinfo:     https://sso.infloapp.com/oauth/userinfo
  End session:  https://sso.infloapp.com/oauth/logout

After registering an app the response includes an "oidc" block with all
of these URLs pre-filled — feed them straight into your client library.

If you see "ClientError: invalid response encountered" from openid-client,
the issuer is almost certainly pointing at https://infloapp.com instead of
https://sso.infloapp.com. Fix the issuer in your OIDC client config.

## Docs for agents

- Capability manifest (machine-readable JSON): https://infloapp.com/api/v1/capabilities
- Plain-text agent quick reference: https://infloapp.com/agents.md
- OpenAPI spec (JSON, canonical):   https://infloapp.com/openapi.json
- API discovery (RFC 9727):         https://infloapp.com/.well-known/api-catalog
- OpenAPI spec (YAML, legacy):      https://infloapp.com/api/clp/openapi.yaml
- Human docs (SPA, render in browser): https://infloapp.com/app/developer/api
- AI Agents tab in the dashboard:   https://infloapp.com/app/developer/api/agents

## Capabilities (summary)

The full list — with auth methods, scopes, base URLs, and primary
endpoints — is at https://infloapp.com/api/v1/capabilities. Today's surface:

- InfloSSO (OIDC) [ga] — OpenID Connect issuer for end-user sign-in (authorization_code, id_token, userinfo). Issuer host is sso.infloapp.com, NOT the API host. (docs: https://infloapp.com/app/developer/sso)
- Personal Access Tokens (PATs) [ga] — Long-lived bearer tokens (infpat_...) for headless agent / CLI operations against developer-portal resources you own. (docs: https://infloapp.com/app/developer/api/agents)
- Developer Apps (Inflo Share OIDC apps) [ga] — Register and manage SSO/OIDC applications under your developer account. Supports both proprietary (POST /api/clp/register-app) and RFC 7591 (POST /oidc/register) registration. (docs: https://infloapp.com/app/developer/api/rest)
- User Search & Public Profiles [ga] — Search discoverable Inflo users and fetch their public profiles. Honours per-user discovery opt-in. Email addresses are never returned. (docs: https://infloapp.com/app/developer/api/users)
- Notifications API [ga] — Send in-app and email notifications to Inflo users. Returns 202 (queued) when the recipient has opted out, to avoid leaking opt-out state. (docs: https://infloapp.com/app/developer/api/notifications)
- Identifier Resolve [ga] — Look up whether a user exists by email or phone — used by InfloSSO's login page to detect existing accounts. Returns verified identities only. (docs: https://infloapp.com/app/developer/api/identifier-resolve)
- User Provisioning [ga] — Create new Inflo user accounts on behalf of InfloSSO during sign-up. Auto-generates the Inflo system email and sends a verification mail. (docs: https://infloapp.com/app/developer/api/user-provisioning)
- Picker Embed (iframe) [ga] — Embeddable user-picker iframe at /embed/picker. Uses the visitor's Inflo session — your app never sees the search query or result set. (docs: https://infloapp.com/app/developer/api/picker-embed)
- Mobile Auth [ga] — OAuth code-exchange and refresh-token endpoints for native mobile apps. JWT access tokens (15min) + rotating refresh tokens (30d). (docs: https://infloapp.com/app/developer/api/mobile-auth)
- Outbound Webhooks [ga] — HMAC-signed event delivery to URLs you register against your app. Retries with backoff for ~24h; replayable from the developer portal. (docs: https://infloapp.com/app/developer/api/webhooks)
- SmartView External API [coming-soon] — Programmatic read/share of SmartViews from third-party apps using short-lived access tokens. Surface in flight; manifest entry exists so agents can discover it now. (docs: https://infloapp.com/app/developer/api/shares)
- MCP server (@inflo/mcp-developer) [ga] — Official Model Context Protocol server. Run via `npx -y @inflo/mcp-developer` with INFLO_PAT in env. Exposes the developer-app surface as typed tools for Claude Desktop, Cursor, and generic MCP clients. (docs: https://infloapp.com/app/developer/api/agents)

## Key endpoints

- POST https://infloapp.com/api/clp/register-app           (create app; scope apps:create)
- GET  https://infloapp.com/api/clp/my-apps                (list apps; scope apps:read)
- GET  https://infloapp.com/api/clp/my-apps/{id}/credentials (view secrets; scope apps:manage)

## Auth

Authorization: Bearer infpat_<64-hex-token>

Tokens are created in the developer portal at https://infloapp.com/app/developer/myapps
under "Personal Access Tokens".

## PAT scopes

- apps:read    — list apps the user owns or co-manages.
- apps:create  — register a new app on the user's behalf.
- apps:manage  — view client_secret / access_token, rotate, edit, delete.

## whoami (verify a PAT)

  curl -H "Authorization: Bearer $INFLO_PAT" \
       https://infloapp.com/api/personal-access-tokens/whoami

Returns { userId, source: "pat", tokenId, scopes, entityIds }.

## Register-app quick start

  curl -X POST https://infloapp.com/api/clp/register-app \
    -H "Authorization: Bearer $INFLO_PAT" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "appName":      "My Agent App",
      "platformType": "web",
      "redirectUris": [{ "uri": "https://example.com/cb", "platform": "web" }]
    }'

## MCP server (recommended for AI agents)

The official @inflo/mcp-developer package exposes these endpoints as MCP
tools that Claude, Cursor, and other MCP clients can invoke directly.

- Package:  https://www.npmjs.com/package/@inflo/mcp-developer
- Source:   https://github.com/inflo/inflo-mcp-developer
- Install:  npx -y @inflo/mcp-developer
- Tools:    whoami, register_app, list_apps, get_app, rotate_secret,
            manage_redirect_uris, manage_aliases

Configure the server with INFLO_PAT (and optional INFLO_API_BASE_URL,
default https://infloapp.com). See https://infloapp.com/docs/agents for one-line install
snippets for Claude Desktop, Cursor, and generic MCP clients.