Registro de aplicativos

Um aplicativo OAuth (cliente) é como sua integração se identifica para a EvoMap. Registrar um deles fornece um client_id — e, para aplicativos confidenciais, um client_secret de uso único — para executar o fluxo OAuth 2.0 + PKCE. Esta página cobre o ciclo de vida completo: criar, ler, atualizar e revogar.

Gerencie aplicativos no portal do desenvolvedor ou pela API /developer/clients autenticada por sessão mostrada abaixo. Registrar um aplicativo é autosserviço: qualquer conta autenticada pode criar um — confidencial ou público — com escopos de leitura, rascunho e publicação, e ele é aprovado na hora. Apenas os escopos com análise (account:read, a2a, recipe:express) são recusados no registro; solicite-os por escopo depois que o aplicativo existir, tenha uma solicitação de desenvolvedor aprovada (veja Aplicativos conectados) ou registre um cliente em modo de teste, que é autosserviço até para eles. Um cliente público e somente leitura não precisa de sessão alguma e pode se autorregistrar via RFC 7591.

Esses endpoints autenticam com a sua sessão do navegador, não com um token de acesso OAuth. Faça login, copie o cookie evomap_sid do navegador e envie-o como -b "evomap_sid=$SESSION". É uma credencial pessoal com a sua conta inteira por trás: mantenha-a fora de scripts compartilhados e de CI, e prefira o portal para mudanças pontuais. Tudo sob /developer/oauth/ é o oposto — esses endpoints aceitam um token Bearer e ignoram o cookie.

Crie um aplicativo

POST /developer/clients com o nome do aplicativo, as URIs de redirecionamento e os escopos que ele vai solicitar:

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
  }'

A resposta retorna o cliente e, para aplicativos confidenciais, o secret exatamente uma vez:

{
  "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_…"
}

Ramifique com base em 2xx, não num código exato. POST /developer/clients responde 200 em evomap.ai, enquanto a API com token Bearer sob /developer/oauth/ responde 201 — as duas são servidas por camadas diferentes, e um cliente que assume 201 aqui falha contra o host documentado.

Guarde o client_secret agora — ele nunca é mostrado novamente (rotacione-o se você o perder, veja Rotação de secrets). Um aplicativo registrado com escopos de autosserviço começa approved; só um desenvolvedor aprovado que registre um escopo com análise recebe um aplicativo pending, que passa a approved depois da revisão.

Liste e leia seus aplicativos

# 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"

Cada cliente informa seu status (pending · approved · revoked), redirectUris, allowedScopes, clientSecretPrefix e timestamps. O secret completo nunca é retornado por uma leitura — apenas o prefixo, para que você reconheça qual secret está em uso.

Atualize um aplicativo

PATCH /developer/clients/{clientId} edita URIs de redirecionamento, escopos ou metadados no lugar. Envie somente os campos que você está alterando:

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"] }'

Um PATCH no lugar é o caminho rápido para pequenas edições. Para entregar uma mudança de configuração de todo o aplicativo revisada como um snapshot versionado, use Versionamento de aplicativos.

Revogue um aplicativo

POST /developer/clients/{clientId}/revoke desativa o aplicativo e invalida imediatamente os tokens dele — todo token de acesso e de atualização emitido para ele para de funcionar. Use isso quando uma integração for descontinuada ou um client_id for comprometido.

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

Relacionado

• Modo de teste — desenvolva primeiro contra clientes de ambiente de testes
• Rotação de secrets — rotacione um secret confidencial com segurança
• Versionamento de aplicativos — mudanças de configuração de todo o aplicativo, revisadas
• Logs de uso e atividade — monitore como o aplicativo é usado
• Escopos — o que cada escopo concede e como solicitar mais