API de grants do Origin
O Origin está em Early Beta e sujeito a alterações.
Um grant vincula um principal a um repositório ou namespace com uma permissão. A API de grants lista os grants concedidos diretamente em um resource, faz upsert do grant que um principal possui e o exclui, permitindo que alterações de acesso sejam automatizadas por script e revisadas como código. As gravações reutilizam as mesmas verificações de acesso do Codebase permissions UI e registram os mesmos eventos de auditoria repository.access_changed e namespace.access_changed.
Os seis endpoints ficam no grupo Grants da referência da API Origin: List Repository Grants, Upsert Repository Grant, Delete Repository Grant, List Namespace Grants, Upsert Namespace Grant e Delete Namespace Grant. Eles compartilham a base URL da API Origin, a autenticação, a pagination e o modelo de error. Esta página aborda os conceitos por trás deles.
Principals
Cada grant indica exatamente um principal.
| Principal | Campo | Identifica |
|---|---|---|
user | user.id | Um usuário do Cherri Code, pelo id user_… encoded que a API da organização usa. |
group | group.id | Um group do Cherri Code, pelo seu id público grp_…: seja um group que a equipe do owner possui, seja um group na organização dessa equipe, retornado como publicId pelas routes de group da API da organização. O id g_… que essas routes recebem é um identifier diferente. |
teamGroup | teamGroup.kind | Um dos built-in groups da equipe proprietária: members (todos os membros da equipe) ou admins (Admin da equipe). |
Um grant de team group é o piso que todo membro desse built-in group tem sobre o resource. Em um namespace, é o namespace floor da equipe. Em um repositório, é o override por repositório da equipe, e excluí-lo faz o repositório voltar ao namespace floor.
Usuários devem pertencer à organização do owner. Um group deve ser um group que a equipe do owner possui ou um group active na organização dessa equipe; os próprios groups de uma equipe podem receber grants mesmo quando a equipe não está linked a uma organização. Os endpoints de gravação respondem a um usuário ou group inexistente exatamente como respondem a um que está fora da organização, ou seja, uma resposta nunca confirma que um principal existe. As respostas de listagem omitem principals que não resolvem mais para um usuário active, um group ou a equipe proprietária.
Permissões
Grants de repositório e grants de namespace usam escalas de permissão diferentes. Ambas correspondem aos presets oferecidos pela Codebase permissions UI.
| Recurso | Valores de permission |
|---|---|
| Repositório | read, write, admin |
| Namespace | PERMISSION_READ, PERMISSION_CONTRIBUTOR, PERMISSION_WRITE, PERMISSION_ADMIN |
PERMISSION_READ, PERMISSION_CONTRIBUTOR e PERMISSION_WRITE concedem esse nível nos repositórios internos do namespace. PERMISSION_ADMIN administra o próprio namespace.
As respostas de listagem informam custom (repositório) ou PERMISSION_CUSTOM (namespace) para um grant que tem uma política customizada. Os endpoints de upsert rejeitam esses valores com InvalidArgument (HTTP 400); políticas customizadas ficam fora da API de grants.
Scopes
Quatro scopes cobrem a API de grants, todos listados em Scopes: repository:settings:read e repository:settings:write para grants de repositório, namespace:settings:read e namespace:settings:write para grants de namespace.
As instalações de app podem ter os quatro, portanto um robô chama a API de grants com um installation access token. User access tokens também funcionam. Solicitar um scope :write concede também o scope :read correspondente. Os list endpoints custam 1 ponto e as gravações custam 5 pontos do budget descrito em Limites de taxa.
Upserts e exclusões
O upsert é um POST que cria ou substitui o grant que um principal detém sobre o resource. Cada principal detém um grant por resource, portanto repetir uma solicitação mantém o mesmo grant e uma permission diferente substitui a anterior. O delete informa o principal no request body e retorna 204 No Content.
Um namespace sempre mantém pelo menos um admin. Um upsert ou delete que deixaria o owner sem nenhum retorna FailedPrecondition (HTTP 400).