Contas de serviço

Uma conta de serviço é uma identidade da organização para automações: pipelines de CI, scripts e integrações. Ela tem papel próprio, não depende de nenhuma pessoa e usa tokens de API com o prefixo atl_sat_. Quando quem configurou a pipeline sai da organização, a pipeline continua funcionando.

Uma conta de serviço não faz login no portal, não recebe e-mail e não aparece como pessoa na lista de membros.

Criar

Owner e Admin gerenciam as contas em Configurações › Contas de serviço › Nova conta de serviço:

Campo	Regra
Nome	Único na organização: letras minúsculas, números e hífens, de 3 a 40 caracteres (ex.: deploy-bot)
Descrição	Opcional
Papel	Viewer, Developer ou Admin. Nunca Owner e nunca acima do papel de quem cria: um Admin cria até Admin
Projetos	Opcional. Sem projeto marcado, a conta acessa todos os projetos da organização

A conta pertence a uma única organização. A criação, a edição, a desativação e a exclusão entram na auditoria.

Limite do plano

A quantidade de contas de serviço (ativas e desativadas; as excluídas não contam) é limitada pelo plano:

	Chave	Starter	Pro	Business	Enterprise
Contas de serviço	apiTokens.maxServiceAccounts	2	10	50	200

A página mostra o uso no topo (por exemplo, "3 de 10"). Com o limite atingido, o botão fica desabilitado com o aviso de upgrade, e a API responde 422 quota.exceeded. Se o limite diminuir, as contas que já existem e os tokens delas continuam funcionando.

Emitir tokens

Na página da conta, em Tokens da conta, Owner e Admin emitem tokens com o mesmo formulário dos tokens pessoais: escopos (ou um modelo, como Deploy por CI) e validade de 1 a 365 dias. Emitir um token exige login recente com segundo fator, como na criação de token pessoal.

• O token é sempre vinculado à organização da conta e herda a restrição de projetos dela.
• A permissão efetiva é a interseção entre o papel da conta e os escopos do token.
• Cada conta tem até 10 tokens ativos.
• Rotação com sobreposição, último uso e revogação funcionam como nos tokens pessoais. O aviso de expiração vai para os Owner e Admin da organização.

Desativar, reativar e excluir

Ação	Efeito
Desativar	Todos os tokens da conta passam a responder 401 na hora. Nenhum token novo pode ser emitido
Reativar	Os tokens ainda válidos voltam a funcionar
Excluir	A conta sai da organização e todos os tokens são revogados. A auditoria mantém o histórico com o nome da conta

Na auditoria

As ações feitas com o token de uma conta de serviço aparecem com a conta como autora (por exemplo, "deploy-bot (conta de serviço)"), o canal service-account, o id do token e o cliente (como atlas-cli/1.0.0). Filtre a auditoria por canal ou por credencial para ver só as ações de uma automação.

Exemplo: deploy por CI

1. Crie a conta deploy-bot com papel Developer, restrita ao projeto web.
2. Emita um token com o modelo Deploy por CI e validade de 90 dias.
3. Guarde o token como segredo da pipeline, na variável CODA_TOKEN.
4. Na pipeline, instale a CLI e rode o deploy pela imagem do build, fixada por digest:

coda deploy --org acme --project web --env production --app api \
  --image registry.example/web@sha256:$DIGEST --wait

Antes do fim da validade, rotacione o token com sobreposição de 24 horas e troque o segredo da pipeline nesse intervalo.

API

As rotas exigem Owner ou Admin e só aceitam login interativo: um token não gerencia contas de serviço.

Método e rota	O que faz
GET, POST /api/v1/orgs/{orgId}/service-accounts	Lista e cria (name, description, role, projectIds)
GET, PATCH, DELETE /api/v1/orgs/{orgId}/service-accounts/{id}	Lê, edita e exclui
POST /api/v1/orgs/{orgId}/service-accounts/{id}/disable e /enable	Desativa e reativa
GET, POST /api/v1/orgs/{orgId}/service-accounts/{id}/tokens	Lista e emite tokens
POST .../tokens/{tokenId}/rotate e DELETE .../tokens/{tokenId}	Rotaciona e revoga um token