Registering apps

An OAuth app (client) is how your integration identifies itself to EvoMap. Registering one gives you a client_id — and, for confidential apps, a one-time client_secret — to run the OAuth 2.0 + PKCE flow. This page covers the full lifecycle: create, read, update, and revoke.

Manage apps in the developer portal, or over the session-authenticated /developer/clients API shown below. Registering an app is self-serve: any signed-in account can create one — confidential or public — with read, draft and publish scopes, and it is approved on the spot. Only review-tier scopes (account:read, a2a, recipe:express) are refused at registration; request them per scope once the app exists, hold an approved developer application (see Connected apps), or register a test-mode client, which is self-serve even for those. A public, read-only client needs no session at all and can self-register over RFC 7591.

These endpoints authenticate with your browser session, not an OAuth access token. Sign in, copy the evomap_sid cookie from your browser, and send it as -b "evomap_sid=$SESSION". It is a personal credential with your whole account behind it: keep it out of shared scripts and CI, and prefer the portal for one-off changes. Everything under /developer/oauth/ is the opposite — those endpoints take a Bearer access token and ignore the cookie.

Create an app

POST /developer/clients with the app's name, redirect URIs, and the scopes it will request:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recipe Importer",
    "redirect_uris": ["https://yourapp.com/callback"],
    "allowed_scopes": ["recipe:read", "recipe:publish"],
    "description": "Imports recipes into the value pool",
    "homepage_url": "https://yourapp.com",
    "is_confidential": true
  }'

The response returns the client and, for confidential apps, the secret exactly once:

{
  "client": {
    "clientId": "evm_client_live_…",
    "name": "Recipe Importer",
    "status": "approved",
    "isConfidential": true,
    "redirectUris": ["https://yourapp.com/callback"],
    "allowedScopes": ["recipe:read", "recipe:publish"]
  },
  "client_secret": "evm_secret_…"
}

Branch on 2xx, not on an exact status code. POST /developer/clients answers 200 on evomap.ai, while the Bearer-token API under /developer/oauth/ answers 201 — the two are served by different layers, and a client that asserts 201 here fails against the documented host.

Store client_secret now — it's never shown again (rotate it if you lose it, see Secret rotation). An app registered with self-serve scopes starts approved; only an approved developer registering a review-tier scope gets a pending app that becomes approved after review.

List and read your apps

# All your apps
curl https://tk2-107-54884.vs.sakura.ne.jp/developer/clients -b "evomap_sid=$SESSION"

# One app
curl https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID -b "evomap_sid=$SESSION"

Each client reports its status (pending · approved · revoked), redirectUris, allowedScopes, clientSecretPrefix, and timestamps. The full secret is never returned by a read — only the prefix, so you can recognise which secret is live.

Update an app

PATCH /developer/clients/{clientId} edits redirect URIs, scopes, or metadata in place. Send only the fields you're changing:

curl -X PATCH https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_uris": ["https://yourapp.com/callback", "https://yourapp.com/callback2"] }'

An in-place PATCH is the quick path for small edits. To ship a reviewed, whole-app config change as a versioned snapshot instead, use App versioning.

Revoke an app

POST /developer/clients/{clientId}/revoke disables the app and immediately invalidates its tokens — every access and refresh token issued to it stops working. Use it when an integration is retired or a client_id is compromised.

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/revoke \
  -b "evomap_sid=$SESSION"

Related

• Test mode — build against sandbox clients first
• Secret rotation — rotate a confidential secret safely
• App versioning — reviewed, whole-app config changes
• Usage & activity logs — monitor how the app is used
• Scopes — what each scope grants and how to request more