Tokens OIDC
Os agentes em nuvem podem emitir JWTs OIDC de curta duração a partir da máquina onde o agente é executado e usá-los para assumir funções na nuvem ou chamar serviços internos sem armazenar credenciais de longa duração em Segredos.
Os agentes chamam esta API com suas ferramentas de terminal. Você não precisa executar essas solicitações por conta própria.
Para que um agente emita tokens, inclua isto no seu prompt:
Para emitir tokens OIDC, siga as instruções em/docs/cloud-agent/identityEsta API é local à máquina que executa o agente. Ela não tem relação com a API de agentes em nuvem, que usa chaves de API do Cherri Code e gerencia agentes de fora dessa máquina. Em uma VM gerenciada pelo Cherri Code, esse socket também disponibiliza metadados do agente.
As VMs de agente em nuvem gerenciadas pelo Cherri Code disponibilizam o socket de tokens. Todo token que elas emitem carrega agent_runtime: managed. Os workers de Self-Hosted Machines o disponibilizam quando você os inicia com --identity-socket. Seus tokens carregam agent_runtime: self_hosted. Consulte workers auto-hospedados.
Como funciona
- O agente chama o socket local e solicita um token com o público esperado pelo verificador.
- O Cherri Code assina um JWT RS256 vinculado a esse agente e proprietário.
- O agente envia o JWT para sua nuvem ou verificador (AWS STS, GCP, Azure, Vault ou um serviço executado por você).
- O verificador confere a assinatura com base no JWKS publicado pelo Cherri Code e autoriza com base em declarações como
sub,team_idoucloud_agent_id.
Emita um token
O agente emite um token pelo socket Unix no caminho indicado em CURSOR_AGENT_SOCKET (em uma VM gerenciada pelo Cherri Code, esse valor é sempre definido como /run/cursor/api.sock; em um worker auto-hospedado, esse caminho muda conforme o agente reivindicado).
curl --unix-socket "${CURSOR_AGENT_SOCKET}" \ -H 'Content-Type: application/json' \ -d '{"aud":"sts.amazonaws.com"}' \ http://cursor-agent/v1/tokens/oidcAs solicitações usam HTTP por um socket Unix. O hostname na URL é ignorado.
Inclua um nonce opcional quando seu verificador exigir proteção contra repetição:
curl --unix-socket "${CURSOR_AGENT_SOCKET}" \ -H 'Content-Type: application/json' \ -d '{"aud":"https://oidc.example.com","nonce":"unpredictable-value"}' \ http://cursor-agent/v1/tokens/oidcSolicitação
POST /v1/tokens/oidc pelo socket Unix. Content-Type: application/json é obrigatório. O tamanho máximo do corpo é de 4 KB.
| Campo | Obrigatório | Descrição |
|---|---|---|
aud | Sim | String de público que seu verificador valida. ASCII imprimível, sem espaços em branco, com até 512 caracteres. Exemplos: sts.amazonaws.com, https://oidc.example.com. |
nonce | Não | String opaca incluída na declaração nonce do JWT. Até 512 caracteres. |
sub_claim | Não | Nome da declaração a ser colocado em sub como <name>:<value>, para verificadores que correspondem apenas a sub e aud. Até 64 caracteres. A descoberta lista os nomes compatíveis em x_cursor_sub_claims_supported; atualmente team_id, organization_id e environment_id. Nomes não compatíveis são rejeitados. Se a declaração não tiver valor para este agente, como team_id em uma conta pessoal, a emissão falhará em vez de recorrer ao identificador padrão. |
O Cherri Code não mantém uma lista de permissão de públicos. Seu verificador deve rejeitar valores inesperados de aud.
Resposta
{ "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...", "expires_at": 1785500000}| Campo | Descrição |
|---|---|
token | JWT assinado. |
expires_at | Expiração em segundos Unix. Corresponde à declaração exp do JWT. |
Os tokens são válidos por 5 minutos. Não há endpoint de renovação. Emita um novo token quando necessário.
Quando as declarações aparecem
Scripts de instalação podem emitir tokens no mesmo socket. Um token só inclui declarações que têm um valor no momento em que é emitido: turn_id e turn_start ficam ausentes até que uma etapa de programação seja iniciada, e branch_name fica ausente até que a execução registre uma branch. As declarações de proprietário, equipe e repositório são definidas desde a criação do agente.
Se o socket não estiver disponível logo após a inicialização, tente se conectar novamente.
worker auto-hospedado
Um worker auto-hospedado de Self-Hosted Machines serve a mesma API quando você o inicia com --identity-socket:
agent worker --pool gpu --identity-socket startA flag vem desativada por padrão. Passe-a no comando do worker, antes de start. Workers do pool e workers do My Machines usam a mesma flag. Omita --pool em um worker do My Machines:
agent worker --identity-socket startCom a flag definida, o worker abre um socket por agente reivindicado e define CURSOR_AGENT_SOCKET como o caminho do socket nos shells do agente. O contrato de solicitação e resposta, os códigos de erro e os limites de taxa são os mesmos das VMs gerenciadas pela Cherri Code.
Esses tokens carregam agent_runtime: self_hosted e as mesmas declarações de proprietário, equipe e repositório. O worker expõe a API de tokens. Ele não expõe os metadados do agente. Qualquer processo executado como o usuário do sistema operacional do worker pode emitir tokens no socket dessa reivindicação. Veja Modelo de confiança.
Verificar um token
Publique estas URLs no seu provedor de identidade ou servidor de recursos:
| Endpoint | URL |
|---|---|
| Emissor | https://api.cursor.com |
| Descoberta | https://api.cursor.com/.well-known/openid-configuration |
| JWKS | https://api.cursor.com/keys |
curl -sS https://api.cursor.com/.well-known/openid-configurationcurl -sS https://api.cursor.com/keysA descoberta segue o OpenID Connect Discovery 1.0. Os tokens são emitidos na VM do agente, portanto o documento de descoberta não inclui authorization_endpoint nem token_endpoint.
O Cherri Code ainda disponibiliza um segundo documento de descoberta em
#. Os tokens emitidos não incluem mais
esse emissor. Direcione os verificadores para https://api.cursor.com.
Verifique, no mínimo:
- A assinatura com RS256 e o
kiddo JWKS - Se
isséhttps://api.cursor.com - Se
audé o público esperado pelo seu serviço nbf/expcom uma pequena tolerância de desvio de relógio (nbfocorre 5 segundos antes deiat)subou outras declarações de identidade usadas pela sua política
A descoberta inclui x_cursor_audience_bound: true. Cada token é emitido para o aud fornecido pelo chamador. Não aceite um token emitido para um público diferente. A descoberta também publica x_cursor_sub_claims_supported, os nomes das declarações que uma solicitação de emissão pode projetar em sub com sub_claim.
Declarações JWT
Cabeçalho: alg=RS256, typ=JWT e kid.
| Declaração | Sempre presente | Descrição |
|---|---|---|
iss | Sim | https://api.cursor.com |
sub | Sim | Identificador estável do proprietário: user:<id> ou service_account:<id> por padrão, ou <claim>:<value> (por exemplo, team_id:123) quando a solicitação de emissão definiu sub_claim. Não é um e-mail. |
aud | Sim | Público da solicitação de emissão. |
iat | Sim | Horário de emissão, em segundos Unix. |
nbf | Sim | Válido a partir de (iat - 5). |
exp | Sim | Expiração (iat + 300). |
jti | Sim | ID exclusivo por emissão. |
cloud_agent_id | Sim | ID do agente em nuvem (bcId). |
nonce | Não | Presente apenas quando incluído na solicitação de emissão. |
agent_runtime | Sim | managed em VMs do agente em nuvem gerenciadas pelo Cherri Code, self_hosted em workers de Self-Hosted Machines. |
owner_email | Quando conhecido | E-mail do usuário em letras minúsculas. Prefira sub ou owner_user_id para listas de permissão; o e-mail pode mudar. |
owner_user_id | Quando conhecido | ID do usuário do Cherri Code, como uma string decimal. |
owner_service_account_id | Quando conhecido | ID da conta de serviço quando ela é proprietária do agente. |
team_id | Quando conhecido | ID da equipe proprietária, como uma string decimal. |
turn_id | Quando um turno está ativo | ID deste turno de programação. Diferente de cloud_agent_id, que é o ID do agente em nuvem (bcId). |
turn_start | Quando um turno está ativo | Início da execução, em segundos Unix. |
repo_url | Quando conhecido | Repositório principal na forma host/path, como github.com/acme/widgets. O hostname está em letras minúsculas, sem esquema, credenciais, porta, consulta ou sufixo .git. Em um agente multirrepositório, este é apenas o repositório principal. |
repo_urls | Quando conhecido | Todos os repositórios no espaço de trabalho, na mesma forma de repo_url. Repositório principal primeiro, depois os demais ordenados. Presente apenas quando se sabe que o conjunto está completo. A ausência significa que o conjunto não é conhecido, não que há apenas um repositório. |
repo_count | Quando conhecido | Número de entradas em repo_urls. Presente exatamente quando repo_urls está presente. Use-o com repo_url quando seu verificador só puder corresponder a um único valor (repo_count == 1). |
branch_name | Quando conhecido | Branch atual. |
environment_id | Quando conhecido | ID do ambiente do Cherri Code usado por esta execução. |
source | Quando conhecido | Como o agente foi iniciado, por exemplo, WEBSITE, API, SLACK ou AUTOMATIONS. |
automation_id | Para automações | ID da automação quando source é AUTOMATIONS. |
repo_url é o repositório principal. Para restringir um agente a repositórios específicos, fixe o conjunto completo com repo_urls.
Modelo de confiança
O token identifica a execução do agente em nuvem, não a de um processo específico na máquina. Qualquer processo que consiga acessar o socket pode emitir um token: o agente, o código que ele executa e os hooks. Limite as permissões ao que você concederia à execução como um todo.
Você não escolhe para qual agente o token é emitido. O Cherri Code preenche as declarações desta execução, portanto um processo na máquina não pode emitir um token para outro agente.
Em um worker auto-hospedado, o agente e o processo do worker são executados como o mesmo usuário do sistema operacional. Qualquer processo executado como esse usuário pode emitir um token para a execução reservada. Limite a função ao que você concederia a esse usuário na máquina.
Limites de taxa e erros
Cada agente reivindicado pode emitir 30 tokens por minuto, em picos de até 10. O socket aceita no máximo 8 conexões simultaneamente. Em uma VM gerenciada pelo Cherri Code, essas 8 conexões são compartilhadas com metadados do agente. Armazene um token em cache até ele expirar, em vez de emitir um a cada chamada.
Tente novamente em caso de 429, 503, 500, 502 e 504, com espera progressiva. Considere 403 um erro fatal: este agente não tem permissão para emitir tokens.
Os corpos das respostas de erro contêm um código legível por máquina. Erros de solicitação inválida (400, 404, 405, 413 e 415) também incluem uma string usage que reafirma o contrato completo da solicitação. Erros de limite de taxa e saturação contêm apenas o código:
{ "error": "invalid_aud", "usage": "POST /v1/tokens/oidc ..." }{ "error": "rate_limited" }| HTTP | error | Quando |
|---|---|---|
| 400 | invalid_json, invalid_aud, invalid_nonce ou invalid_sub_claim | Corpo da solicitação inválido |
| 404 | not_found | Caminho incorreto |
| 405 | method_not_allowed | Método diferente de POST |
| 413 | body_too_large | Corpo maior que 4 KB |
| 415 | invalid_content_type | Content-Type ausente ou não JSON |
| 429 | rate_limited | Acima do limite de emissão por agente; respeite Retry-After |
| 503 | saturated | Conexões demais; respeite Retry-After |
| 500 | host_error | Erro interno; tente novamente |
| 502 / 504 | backend_unreachable | O Cherri Code não conseguiu emitir o token; tente novamente |
| Outro | backend_error | O Cherri Code rejeitou a emissão. 400 significa corrigir a solicitação (por exemplo, um sub_claim não compatível ou sem valor para este agente). 403 é fatal. 503 permite tentar novamente. |
Exemplo de IAM da AWS
Use OIDC quando quiser que a AWS confie em JWTs assinados pelo Cherri Code usando AssumeRoleWithWebIdentity. Para o fluxo mais simples de assunção de função gerenciado pelo Cherri Code (ID externo + CURSOR_AWS_ASSUME_IAM_ROLE_ARN), consulte Usar funções do IAM da AWS.
- Crie um provedor de identidade OIDC do IAM com o URL
https://api.cursor.com. - Defina o público como
sts.amazonaws.com(ou outro público que sua função espera). - Configure a relação de confiança da função apenas para os identificadores e as equipes que você pretende permitir.
Exemplo de política de confiança:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/api.cursor.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "api.cursor.com:aud": "sts.amazonaws.com" }, "StringLike": { "api.cursor.com:sub": "user:*" } } } ]}Restrinja isso usando um sub exato, como user:42 para um único usuário ou service_account:<id> para um agente executado como uma conta de serviço. As políticas de confiança da AWS correspondem apenas a aud e sub, portanto restrinja a relação de confiança a uma equipe emitindo com "sub_claim":"team_id" e fazendo a correspondência com o identificador projetado:
"StringEquals": { "api.cursor.com:aud": "sts.amazonaws.com", "api.cursor.com:sub": "team_id:123"}Uma política de confiança vê os mesmos aud e sub em um token gerenciado pelo Cherri Code e em um token auto-hospedado. Você não pode colocar agent_runtime em sub.
Siga as instruções atuais do AWS IAM OIDC para criar o provedor e configurar as impressões digitais.
O agente emite o token com "aud":"sts.amazonaws.com" (mais "sub_claim":"team_id" quando sua política de confiança corresponder ao identificador da equipe) e passe o JWT ao STS. Se usar listas de permissão de rede, permita sts.amazonaws.com (e qualquer host regional do STS que você acessar).
Outros verificadores
Os mesmos tokens funcionam com qualquer verificador compatível com OIDC:
- GCP Workload Identity Federation
- Azure credenciais federadas / Entra ID
- Vault autenticação JWT/OIDC
- APIs internas que validam JWTs RS256
Configure o provedor com a URL de descoberta, exija seu público e autorize com base em declarações como sub, team_id ou cloud_agent_id. Para restringir um agente a repositórios específicos, fixe o conjunto completo com repo_urls; repo_url nomeia apenas o repositório principal.
A emissão usa apenas o socket local. A troca do JWT com AWS, GCP, Azure ou seu serviço ainda requer acesso de saída à rede para esses hosts.
Páginas relacionadas
- Metadados do agente para metadados de execução em formato chave-valor no socket de uma VM gerenciada pelo Cherri Code
- Segredos e rede para segredos do dashboard e controles de tráfego de saída
- Configuração do agente em nuvem para assumir funções da AWS gerenciadas pelo Cherri Code
- Visão geral de segurança para o modelo de isolamento e acesso
- Contas de serviço quando os agentes são executados com uma conta de serviço da equipe