Atuando em nome de usuários

Os apps Origin usam tokens de usuário da instalação para atuar em nome de membros do namespace em que estão instalados. Cada solicitação fica limitada às permissões que a instalação e o usuário têm em comum.

Use a URL base da API Origin e o modelo de erros. Emita tokens com um JWT do app.

Como funciona

1. Um administrador do espaço de trabalho aprova o escopo namespace:user_tokens:write para a instalação do seu app.
2. Opcionalmente, confirme a identidade do usuário no Cherri Code. O Origin retorna um comprovante assinado com o ID user_… dele.
3. Assine um JWT do app e emita um token de usuário da instalação para o ID ou email do usuário.
4. Use o token de usuário da instalação com a REST API ou com o Git via HTTPS até expiresAt e, depois disso, emita outro.

Solicite o escopo

Adicione namespace:user_tokens:write ao parâmetro scope da URL de instalação. Se a instalação já existir, envie também include_granted_scopes=true para que o admin precise aprovar apenas o novo escopo.

/codebase/apps/install  ?client_id=APP_ID  &scope=namespace:user_tokens:write%20repository:pull_requests:write  &redirect_uri=REGISTERED_CALLBACK  &state=RANDOM_ANTI_FORGERY_VALUE  &include_granted_scopes=true

Esse escopo permite que a instalação emita tokens para qualquer membro ativo do namespace. Não é possível incluí-lo nos scopes de um token. Os demais escopos aprovados pelo admin continuam limitando as permissões de cada token.

Quando confirmar um usuário

A confirmação do usuário é opcional: a aprovação do admin para namespace:user_tokens:write já abrange todos os membros do namespace.

Confirme um usuário para vincular uma conta no seu produto à conta do Cherri Code dele ou para verificar a identidade dele, em vez de confiar em um endereço de email digitado. O comprovante atesta o ID user_…, o email e a associação ao namespace do usuário com sessão iniciada no momento da confirmação.

Comprovantes atestam a identidade, mas não concedem nenhuma permissão. O Create Installation User Token não aceita nem exige um comprovante.

Confirmação do usuário

Envie o usuário para o Origin

Abra esta URL no navegador do usuário:

/codebase/apps/user-confirmation  ?installation_id=INSTALLATION_ID  &redirect_uri=REGISTERED_CALLBACK  &state=RANDOM_ANTI_FORGERY_VALUE

Envie cada parâmetro no máximo uma vez. A ausência de parâmetros obrigatórios ou a repetição de parâmetros gera um erro após o login.

O que o usuário vê

Usuários desconectados fazem login no Cherri Code e depois retornam ao mesmo link, com os mesmos parâmetros. O Origin valida os parâmetros após o login, então até links malformados passam pelo login antes de exibir um erro.

O Origin mostra o nome, o ícone e a descrição do seu app junto com o namespace da instalação. Ele também lista os dados que seu app vai receber:

• ID de usuário do Cherri Code (user_…)
• E-mail
• Slug e ID do namespace Origin

A página explica que, ao confirmar, o usuário compartilha sua identidade e sua associação atual ao namespace, sem conceder acesso ao repositório. O usuário escolhe Confirm ou Cancel.

Somente membros ativos da equipe proprietária, ou o proprietário de um namespace pessoal, podem confirmar.

Callback

Após a confirmação, o Origin redireciona para o seu callback:

https://app.example.com/origin/confirm?confirmation_receipt=RECEIPT_JWT&state=RANDOM_ANTI_FORGERY_VALUE

Verifique o comprovante de confirmação antes de ler as reservas de usuário contidas nele. O callback inclui state somente se a URL de confirmação tiver fornecido um valor não vazio. Confie na declaração state assinada, e não no parâmetro da query.

Cancelar ou não conseguir confirmar não gera callback nem redirecionamento. Trate a ausência de callback como "não confirmado" e permita que o usuário recomece.

Comprovante de confirmação

confirmation_receipt é um JWT compacto assinado pelo Origin com as mesmas chaves usadas nos comprovantes de instalação.

Cabeçalho JOSE:

{  "alg": "EdDSA",  "kid": "origin-key-id",  "typ": "origin-user-confirmation-receipt+jwt"}

Reservas:

{  "iss": "https://api.cursor.com/v1/origin",  "aud": "app_01...",  "sub": "user_01...",  "installation_id": "i_01...",  "namespace_id": "ns_01...",  "email": "[email protected]",  "iat": 1786465200,  "exp": 1786465500,  "jti": "RECEIPT_UUID",  "state": "ORIGINAL_VALUE"}

• aud é o app ID do seu app; sub é o ID user_… do usuário confirmado, usado como userId ao emitir o token.
• installation_id e namespace_id identificam a instalação e o namespace em que a associação foi confirmada.
• email é o email da conta do usuário no momento da confirmação.
• Os comprovantes expiram cinco minutos após a emissão. jti é único para cada comprovante.
• state só é incluído se a URL de confirmação tiver fornecido um valor não vazio.

Verifique o comprovante antes de confiar no callback:

1. Obtenha a signing key no JWKS com base no cabeçalho kid.
2. Exija alg: EdDSA e typ: origin-user-confirmation-receipt+jwt para diferenciar comprovantes de confirmação de comprovantes de instalação e de access tokens.
3. Valide a assinatura, iss, aud e exp.
4. Confira se installation_id e o state assinado correspondem aos valores que você enviou.

Rejeite o callback se alguma verificação falhar.

Erros de confirmação

Em caso de falha, o usuário permanece na página do Cherri Code sem que seu callback seja chamado.

Emitir um token de usuário da instalação

Chame Create Installation User Token, POST /v1/origin/app/installations/{installationId}/user_access_tokens, com um JWT do app. Defina apenas um dos campos: userId ou userEmail.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID/user_access_tokens' \  --header 'Authorization: Bearer APP_JWT' \  --header 'Content-Type: application/json' \  --data '{  "userId": "user_01...",  "scopes": [    "repository:pull_requests:write"  ],  "repositoryIds": [    "repo_01..."  ]}'

{  "token": "YOUR_INSTALLATION_USER_TOKEN",  "expiresAt": "2026-01-01T00:15:00Z"}

O usuário deve ter uma conta do Cherri Code ativa e atender às regras de associação ao namespace. Usuários desconhecidos, não membros e emails que correspondem a vários membros retornam o mesmo 403.

Com scopes e repositoryIds definidos, a emissão só é bem-sucedida se a instalação e o usuário tiverem, cada um, todos os escopos solicitados em todos os repositórios listados. Com menos limites, as permissões são verificadas a cada solicitação.

Tempo de vida

O expiresAt fica no máximo 15 minutos após a emissão e nunca depois do exp do JWT do app, assim como nos tokens de acesso da instalação. Não há refresh token: após a expiração, emita outro com um novo JWT do app. Cada emissão consome 1 ponto do limite de taxa do JWT do app.

Usar o token

Trate os tokens de usuário da instalação como opacos: não inspecione nem interprete o conteúdo deles. Envie o token como credencial Bearer para a REST API ou como senha para Git via HTTPS com o nome de usuário x-access-token:

Authorization: Bearer YOUR_INSTALLATION_USER_TOKEN

Cada solicitação precisa estar dentro dos escopos aprovados e da seleção de repositórios da instalação, das concessões no Origin do usuário e dos limites do token. Caso contrário, ela retorna 403, ou 404 se o resource não estiver visível.

Os campos de ator identificam o usuário e podem incluir performedVia.app com o id do seu app e um displayName opcional. A atribuição se aplica à ação descrita por esse campo: no autor de um comentário, ela identifica o app que criou o comentário, e não um app que o tenha editado ou excluído depois. performedVia fica ausente em ações diretas do usuário e pode ficar ausente quando os dados de delegação não estão disponíveis.

Erros de emissão

Revogação

Não é possível revogar tokens individualmente. Estas alterações afetam o acesso dos tokens:

• Desinstalar ou excluir o app invalida os tokens de usuário dele antes de expiresAt. As solicitações retornam 401.
• Encerrar a conta do Cherri Code do usuário invalida os tokens dele. As solicitações retornam 401.
• Remover namespace:user_tokens:write ou suspender a instalação impede a emissão de novos tokens. Os tokens emitidos expiram em expiresAt.
• Alterações nas concessões da instalação ou do usuário entram em vigor até expiresAt, no máximo.

Notas de segurança

• Emita tokens apenas no momento em que forem necessários, com os menores scopes e repositoryIds possíveis. Trate tokens como senhas: não os armazene nem os registre em logs.
• Vincule contas pelo sub, não pelo email: o ID user_… do usuário é estável, mas o email pode mudar.
• Verifique os endereços de email antes de emitir tokens com userEmail. Um endereço digitado pode corresponder a outro membro.
• Use cada comprovante apenas uma vez. Registre o jti dele e rejeite repetições durante os cinco minutos de validade.
• Um comprovante não é uma credencial: não o envie como Bearer token nem o registre em logs, pois ele contém o email do usuário.
• Os comprovantes refletem a associação no momento da confirmação. Cada emissão verifica a associação novamente, então um comprovante armazenado não permite emitir tokens para alguém que já saiu.