API de OAuth

Ponto de token OAuth 2.0 (RFC 6749 §3.2) para JWTs de agentes. grant_type refresh_token gira uma credencial opaca de atualização (RFC 9700): cada uso retorna um novo par; um request_id (16 a 200 caracteres) faz uma nova tentativa exata retornar a mesma resposta enquanto sua credencial e concessão estiverem ativas e o sucessor ainda for atual, sem prazo de tentativa por tempo decorrido.

Qualquer outro reuso de um token de atualização substituído revoga toda a família (invalid_grant). Uma associação ou projeto selecionado removido retorna invalid_scope com error_description começando com "project_selection_inactive:"; a credencial de atualização não é consumida.

Descubra associações ativas com GET /api/projects, intercepte-as com a seleção previamente consentida e tente novamente com projects= e um novo request_id. Nunca finalize a família de atualizações para este erro de seleção.

O estreitamento do escopo solicitado aplica-se independentemente a cada projeto e à autoridade de identidade; um escopo explícito sem identidade exclui a autoridade de identidade. grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) com subject_token_type urn:screenrig:token-type:identity-credential ou urn:screenrig:token-type:project-token responde unsupported_token_type: credenciais legadas foram aposentadas, e a instalação faz login novamente com screenrig login. resource (RFC 8707) é https://api.<domain>/api ou ausente; projects seleciona até 64 IDs de projeto consentidos.

Omissão seleciona tudo apenas quando o conjunto cabe; caso contrário, o cliente deve escolher um subconjunto. project_id seleciona um durante a liberação de compatibilidade. A concessão de um app conectado tem o recurso único https://api.<domain>/mcp, que um refresh pode omitir.

Clientes são públicos (apenas client_id), ou um app conectado cujo metadata declara private_key_jwt autentica com client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer e um client_assertion (iss e sub seu client_id, aud o emissor ou este endpoint como uma string, exp dentro de 5 minutos de iat, um jti usado uma vez, kid nomeando uma de suas chaves; EdDSA, ES256 ou RS256). grant_type authorization_code resgata o código de um app conectado em 60 segundos com o redirect_uri exato e o PKCE code_verifier; resource deve estar ausente ou ser o autorizado; um segundo resgate revoga a concessão criada pelo código. grant_type client_credentials é de um cliente de serviço: autentica com uma client assertion (uma de suas chaves registradas) ou seu segredo por HTTP Basic (client_secret_basic; segredo no corpo é recusado) e recebe um token de serviço de 15 minutos para seu projeto, audiência api ou (resource https://api.<domain>/mcp) mcp, escopo dentro de suas capacidades e nível de acesso, e sem refresh token; 600 por cliente por hora.

Erros são JSON RFC 6749 {error, error_description} com Cache-Control no-store; enquanto o servidor não os emite responde temporarily_unavailable (503).

Limites de taxa respondem 429 rate_limited com Retry-After: 1200 solicitações por endereço de cliente por hora neste e no endpoint de revogação, 60 atualizações por concessão por hora, 30 trocas por credencial legada por hora. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) consulta um login de dispositivo: authorization_pending até que uma pessoa aprove, slow_down quando consultado antes do intervalo (que então cresce 5 segundos), access_denied quando negado, expired_token após 10 minutos, então a resposta do token.

Uma nova instalação recebe um par de tokens; um login iniciado com o token de acesso de uma instalação existente adiciona o projeto aprovado a essa concessão e recebe apenas um token de acesso, sem rotacionar o token de atualização. Consultar o mesmo device_code novamente retorna a mesma resposta até que a concessão rotacione pela primeira vez ou 10 minutos se passem, então invalid_grant.

Apenas POST, codificado em formulário, sem string de consulta.

RFC 8628 §3.1 autorização de dispositivo para `screenrig login`. scope é access:manage (padrão), access:propose ou access:read; project_id sugere o projeto que a pessoa aprova; name, agent_type, platform e version descrevem a instalação e são mostrados ao aprovador conforme relatado pelo dispositivo; install_source (opcional) indica de onde a instalação veio e é mantido no agente que a aprovação cria.

Sem Authorization inicia uma nova instalação. Com Authorization: Bearer e um token de acesso do agente com escopo de identidade, solicita adicionar um projeto à concessão dessa instalação, ou elevar um projeto Somente leitura para Gerenciar.

A pessoa insere user_code em verification_uri (ou segue verification_uri_complete) e aprova no dashboard; o dispositivo consulta o endpoint de token com device_code a cada intervalo de segundos.

Limites de taxa respondem 429 rate_limited com Retry-After: 10 por endereço de cliente por hora e 600 por hora para toda a frota, atrás dos endpoints de 1200 por endereço por hora. Erros são JSON RFC 6749 com Cache-Control no-store; enquanto o servidor não emitir, responde temporarily_unavailable (503). Apenas POST, codificado em formulário, sem query string.

Ponto de autorização OAuth 2.0 para apps conectados (clientes MCP). client_id é uma URL de documento de metadados de ID de cliente (https, porta 443, buscada sem redirecionamentos, 64 KiB e 5 segundos no máximo, apenas endereços públicos) ou um id de cliente registrado.

A solicitação é validada nesta ordem: o cliente, o redirect_uri exato (um redirecionamento http de loopback para 127.0.0.1, [::1] ou localhost corresponde em qualquer porta), response_type code, code_challenge com code_challenge_method S256, resource (https://api.<domain>/mcp, outro recurso MCP cujos metadados de recurso protegido nomeiam este servidor, ou ausente) e então scope (access:read, o padrão, access:propose, access:manage e nomes de capacidades).

Um cliente desconhecido ou redirect_uri responde com uma página de erro HTML e nunca redireciona; qualquer erro posterior redireciona para o redirect_uri com error, error_description, state e iss (RFC 9207).

Sucesso responde 303 para a página de consentimento do dashboard, onde uma pessoa escolhe o projeto, o nível de acesso (Somente leitura por padrão, Propor ou Gerenciar) e as capacidades; aprovação redireciona com código, estado e iss. 30 solicitações por endereço cliente por minuto.

Revogação RFC 7009. Uma credencial de atualização opaca (ou um JWT de atualização de versão anterior), ou um JWT de acesso de agente, emitido para o cliente revoga sua concessão; os tokens de acesso da concessão são recusados em segundos. Um token desconhecido, expirado ou estrangeiro também responde 200. Apenas POST, codificado em formulário.

Metadados do servidor de autorização RFC 8414 para o servidor de autorização do agente.

Metadados de recurso protegido RFC 9728 para /mcp, nomeados pelo resource_metadata de cada /mcp 401.

Metadados de recurso protegido RFC 9728 para /api.

Uma autorização pendente de app conectado para a página de consentimento: o nome e domínio do cliente conforme declarados em seus metadados (nenhum logo é buscado), se é um cliente registrado, o host de redirecionamento, e o nível de acesso e capacidades solicitadas. Autorizações desconhecidas, expiradas ou resolvidas são not_found.

Aprova um app conectado para um dos projetos da pessoa após prova recente (tipo oauth_authorization_approval, sujeito o id da autorização): cria a identidade do agente do app (tipo mcp_client, a pessoa responsável), sua associação e concessão com o acesso escolhido (ler ou gerenciar; omitido mantém o nível solicitado, padrão ler) e capacidades (subconjunto do solicitado), e responde o redirect_uri, carregando código, estado e iss, para onde a página navega.

O código é válido por 60 segundos. Um membro limitado a telas não conecta agentes, não emite credenciais nem gerencia as pessoas do projeto: outside_screen_scope (peça ao proprietário do projeto).

Nega um app conectado após prova recente (kind oauth_authorization_denial) e responde o redirect_uri, com error=access_denied, state e iss, para o qual a página navega. Um membro limitado a telas não conecta agentes, não emite credenciais nem gerencia as pessoas do projeto: outside_screen_scope (peça ao proprietário do projeto).