netaart/neta-developer-skill/neta-developer-skill

Neta Developer Skill

Help developers build third-party SPAs on the Neta Open Platform.

Neta is operated by Viscept Limited.

Developer access

To become a Neta developer, contact staff via Discord: https://discord.com/channels/1196028153085296651/1497137199001501768

Once granted developer privilege, you receive a DEV_TOKEN (scopes: user:read, develop, asset:read, asset:write, generate, llm). This token is issued by the Neta Developer Portal and provides full access to all platform APIs. You can use it to manage your developer apps (create, list, update, delete) via the CLI toolkit, or to call any platform API directly.

Your SPA issues its own tokens to end users with the scopes you registered for your app: user:read, asset:read, asset:write, generate, llm. SPA access tokens expire after 1 hour; a refresh token is included. Your client code is responsible for refreshing proactively to maintain a smooth user experience.

All users who sign in via Neta OAuth are automatically registered as Neta app users (or logged in if they already have an account).

Core workflow

1. Register a developer app — via the CLI toolkit (bin/neta-dev-app) or the Neta Developer Portal
2. Implement OAuth2 + PKCE — against the Neta OAuth service at https://auth.neta.art
3. Request scopes — match to the smallest set your app needs
4. Call platform APIs — with Authorization: Bearer <access_token>
5. Poll tasks — for async generation results

If your SPA doesn't call Neta backend APIs, registration is optional.

Scope selection

Start with the smallest set. Update later via PATCH /v1/developer/apps/{uuid}.

The develop scope is reserved for the official portal. Third-party SPAs cannot request it.

Auth flow (OAuth2 + PKCE)

1. Generate code_verifier (512-bit entropy) and code_challenge (SHA-256)
2. Redirect to https://auth.neta.art/oidc/auth with client_id, redirect_uri, response_type=code, scope=openid offline_access <scopes>, code_challenge, code_challenge_method=S256, state, nonce, resource=https://api.talesofai
3. Handle callback: validate state, exchange code + code_verifier for tokens at https://auth.neta.art/oidc/token
4. Validate nonce in id_token payload
5. Store tokens in sessionStorage
6. Refresh access token when within 60 seconds of expiry

Reference implementation: assets/demo-spa/auth.js.

Demo SPA quickstart

cp -r assets/demo-spa my-neta-app
cd my-neta-app
# Edit config.js: replace YOUR_CLIENT_ID with your CLIENT ID from the portal
python3 -m http.server 9999

Zero-dependency vanilla JS covering all five scopes across 8 tabs. See assets/demo-spa/README.md for architecture, security model, and production hardening.

The demo is a reference starting point. For more ambitious projects, adapt it to any language or framework — TypeScript, React, Vue, or your preferred stack. All auth and API logic is framework-agnostic.

Security

• No BFF: Tokens live in sessionStorage only. SPA owners are responsible for securing their deployment. See demo README for XSS prevention patterns.
• CSP: Update the <meta> tag in index.html when adding new hosts. See demo README for the CSP reference table.
• Redirect URI: Exactly 1 URI. http://localhost:*, https://*.talesofai.com, or https://*.cohub.run. See references/developer-app-crud.md for the full rules table.
• Logout: Client-side only (sessionStorage.clear() + reload). Tokens are not revoked at the OAuth service.

Adding API calls

Follow the namespaced pattern in api.js. Each scope maps to a namespace:

• UserAPI.* — profile, AP balance, delta history
• AssetAPI.* — characters, elementums, campaigns
• GenerateAPI.* — image/video/song generation, artifacts, upload, task polling
• LLMAPI.* — streaming chat completions

To add a new endpoint:

1. Add a function to the appropriate namespace using the callApi(method, path, body, query) helper
2. Add UI in index.html and wire logic in app.js
3. Update CSP connect-src / img-src / media-src if using new hosts

api.js is the source of truth for endpoint specs.

Glossary

Terms users may use, especially Chinese speakers:

Resources

• Demo SPA reference: assets/demo-spa/README.md — architecture, security model, CSP guide, production checklist
• CLI toolkit: references/developer-app-crud.md — manage developer apps from the terminal
• API specs: assets/demo-spa/api.js — full endpoint listing (code is source of truth)
• Auth implementation: assets/demo-spa/auth.js — OAuth2 PKCE reference client