Comece a usar a API de administração do Atlas
Nesta página
- A autenticação OAuth 2.0 para acesso programático ao Atlas está disponível como um recurso de visualização.
- O recurso e a documentação correspondente podem mudar a qualquer momento durante o período de Pré-visualização. Para utilizar a 2.0 autenticação OAuth, crie uma conta de serviço do para utilizar em seus pedidos para a API de Administração do Atlas .
Importante
Cada Atlas Administration API tem seus próprios recursos e requer configuração inicial.
Você pode acessar os servidores da API de administração do Atlas apenas pela internet pública. A API Atlas Administration não está disponível em conexões que usam emparelhamento de rede ou endpoints privados.
Para saber mais, consulte Atlas Programmatic Access.
A API de Administração do Atlas segue os princípios do estilo de arquitetura REST para expor uma série de recursos internos que permitem o acesso programático aos recursos do Atlas. Para saber mais, consulte Referência da API de Administração do Atlas.
Conceder acesso programático ao Atlas
Você pode conceder acesso programático a uma organização ou projeto usando um dos dois métodos de autenticação a seguir:
Chaves de API | Conta de serviço (prévia) |
|---|---|
Método legado de autenticação no Atlas que usa HTTP Digest Authentication. | Novo método de autenticação no Atlas usando o protocolo-padrão da indústria OAuth 2.0 com o fluxo de credenciais do cliente. Atualmente em prévia. |
As chavesde API têm duas partes: uma chave pública e uma chave privada. Essas duas partes têm a mesma função que um nome de usuário e uma senha quando você faz solicitações de API ao Atlas. | Uma conta de serviço permite gerenciar permissões e criar tokens de acesso. Uma conta de serviço tem um ID de cliente e um segredo que funciona como um nome de usuário e uma senha para criar tokens de acesso. Um token de acesso permite fazer solicitações de API para o Atlas. |
O Atlas faz o hash da chave pública e da chave privada usando um valor exclusivo chamado nonce. O nonce é válido apenas por um curto período de tempo, conforme a especificação de autenticação HTTP Digest. Isso é para evitar ataques de repetição, para que você não possa armazenar em cache um nonce e usá-lo para sempre. | Depois de criar uma conta de serviço, você usará o ID de cliente e o segredo para gerar um token de acesso que autentica suas solicitações de API. Os tokens de acesso são válidos apenas por 1 hora (3600 segundos) conforme a especificação OAuth.2.0 A expiração dos tokens de acesso evita ataques de repetição, em que um token de acesso vazado poderia ser usado sem restrição de tempo. |
As funções do Atlas limitam quais operações as chaves de API podem executar. Você deve conceder funções às chaves de API, como faria com os usuários, para garantir que as chaves de API possam chamar os endpoints de API sem erros. | As funções do Atlas limitam quais operações uma conta de serviço pode executar com seu token de acesso. Você deve conceder funções às contas de serviço, como faria com os usuários, para garantir que o token de acesso possa chamar os endpoints da API sem erros. |
Atlas vincula muitos recursos a um projeto. Muitos URL de recursos de API seguem o formato de | Atlas vincula muitos recursos a um projeto. Muitos URL de recursosAPI seguem o formato de |
Cada chave de API pertence a apenas uma organização, mas você pode conceder acesso a chaves de API a qualquer quantidade de projetos nessa organização. | Cada conta de serviço pertence a apenas uma organização, mas você pode conceder acesso a uma conta de serviço a qualquer número de projetos nessa organização. |
Você não pode usar chaves API para efetuar login no Atlas por meio da interface do usuário do Atlas. | Não é possível usar uma conta de serviço ou seu token de acesso para fazer login no Atlas por meio da IU do Atlas. |
Opcional: Exigir uma lista de acesso IP para a API de administração do Atlas
O Atlas permite que você faça solicitações de API do Atlas Administration a partir de qualquer endereço na Internet, a menos que você exija uma lista de acesso de IP, que limita as solicitações de API somente àquelas provenientes de endereços IP ou CIDR baseados em localização que você especificar na lista de acesso de IP.
Cada método de autenticação tem sua própria lista de acesso IP. Se você exigir uma lista de acesso IP para todas as solicitações de API de administração do Atlas, defina pelo menos uma entrada da lista de acesso IP para suas chaves de API ou contas de serviço antes de poder usá-las para fazer solicitações de API.
Quando você cria uma organização usando a UI do Atlas, o Atlas habilita o requisito de lista de acesso à API por padrão. Para desativar, alterne Require IP Access List for the Atlas Administration API para OFF ao criar uma organização.
Para definir sua organização para exigir listas de acesso IP para cada solicitação da API de administração do Atlas após a criação da organização, siga estas etapas:
No Atlas, acesse a página Organization Settings.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Clique no ícone Organization Settings próximo ao menu Organizations.
A página Configurações da organização é exibida.
Gerenciar Acesso Programático a uma Organização
Use os procedimentos a seguir para conceder acesso programático a uma organização por meio de chaves de API ou de uma conta de serviço. Para saber mais sobre esses dois métodos de autenticação, consulte Autenticação da API de Administração do Atlas.
Importante
No momento, as contas de serviço estão em prévia. Para saber mais, consulte Visão geral das contas de serviço.
Acesso necessário
Para executar as seguintes ações, você deve ter acesso do Organization Owner ao Atlas.
Criar uma API chave
Para criar uma chave API em uma organização usando o Atlas CLI, execute o seguinte comando:
atlas organizations apiKeys create [options]
Para saber mais sobre a sintaxe e os parâmetros do comando, consulte a documentação do Atlas CLI para atlas organizations apiKeys create.
Adicionar uma entrada da lista de acesso à API para a chave de API
Para criar uma entrada de lista de acesso IP para sua chave API utilizando o Atlas CLI, execute o seguinte comando:
atlas organizations apiKeys accessLists create [options]
Para saber mais sobre a sintaxe e os parâmetros do comando, consulte a documentação do Atlas CLI para atlas organizations apiKeys accessLists create.
No Atlas, acesse a página Organization Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Execute uma das seguintes etapas:
Selecione Organization Access no menu Access Manager na barra de navegação.
Clique em Access Manager na barra lateral.
A página Organization Access Manager é exibida.
Insira o API Key Information.
Insira um Description.
No menu Organization Permissions, selecione a nova função ou funções para a chave de API.
Copie e salve a Private Key.
A chave privada atua como a senha ao fazer solicitações de API.
Aviso
Copie e salve chaves públicas e privadas
O Private Key é mostrado apenas uma vez: nesta página. Clique no botão Copy para adicionar a chave privada à área de transferência. Salve e proteja as chaves pública e privada.
Adicione uma API Access List Entry.
Clique em Add Access list Entry.
Insira um endereço de IP ou bloco CIDR a partir do qual você deseja que o Atlas aceite solicitações de API para essa chave de API.
Você também pode clicar em Use Current IP Address se o host que você está usando para acessar o Atlas também fizer solicitações de API usando essa chave de API.
Clique em Save.
No Atlas, acesse a página Organization Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Execute uma das seguintes etapas:
Selecione Organization Access no menu Access Manager na barra de navegação.
Clique em Access Manager na barra lateral.
A página Organization Access Manager é exibida.
Insira as informações da conta de serviço.
Insira um Name.
Insira um Description.
Selecione uma duração no menu Client Secret Expiration.
No menu Permissões da organização, selecione a nova função ou funções para a conta de serviço.
Adicione uma API Access List Entry.
Clique em Add Access List Entry.
Insira um endereço IP ou bloco CIDR do qual você deseja que o Atlas aceite solicitações de API para esta conta de serviço.
Você também pode clicar em Use Current IP Address se o host que você está usando para acessar o Atlas também fizer solicitações de API usando esta conta de serviço.
Clique em Save.
Você pode usar a API de administração do Atlas para criar uma conta de serviço para sua organização.
Depois de criar a conta de serviço, copie e salve o {CLIENT-ID} e o {CLIENT-SECRET} do resultado, que deve ser semelhante ao exemplo a seguir. Esse é o único momento em que você pode visualizar o segredo completo do cliente. Você precisará dessas informações quando fizer uma solicitação de API.
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
Conceder acesso de programação a um projeto
Use os procedimentos a seguir para conceder acesso programático a um projeto por meio de chaves de API ou de uma conta de serviço. Para saber mais sobre esses dois métodos de autenticação, consulte Autenticação da API de Administração do Atlas.
Importante
No momento, as contas de serviço estão em prévia. Para saber mais, consulte Visão geral das contas de serviço.
Acesso necessário
Para dar acesso às chaves de API a um projeto, você deve ter o acesso Project Owner a esse projeto.
Para dar a uma conta de serviço acesso a um projeto, você deve ter o acesso Organization Owner à organização proprietária do projeto.
Atribuir acesso à organização existente a um projeto
Se você já criou chaves de API ou contas de serviço para uma organização, pode atribuí-las a um projeto para conceder a esse projeto acesso à API Atlas Administration.
Para atribuir uma chave API a um projeto utilizando o Atlas CLI, execute o seguinte comando:
atlas projects apiKeys assign <ID> [options]
Para saber mais sobre a sintaxe e os parâmetros do comando, consulte a documentação do Atlas CLI para atlas projects apiKeys assign..
Para atribuir chaves de API da organização a um projeto usando a interface do usuário do Atlas:
No Atlas, acesse a página Project Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Execute uma das seguintes etapas:
Selecione Project Access no menu Access Manager na barra de navegação.
Ao lado do menu Projects, expanda o menu Options, clique em Project Settings e clique em Access Manager na barra lateral.
A página Project Access Manager (Gerente de acesso do projeto) é exibida.
Adicione a chave API ao projeto.
Digite a chave pública no campo.
No menu Project Permissions, selecione a nova função ou funções para a chave de API.
Aviso
Se você atribuir uma conta de serviço da organização a um projeto, o Project Owner poderá gerenciar a conta de serviço, incluindo a rotação de segredos e a atualização da lista de acesso IP.
No Atlas, acesse a página Project Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Execute uma das seguintes etapas:
Selecione Project Access no menu Access Manager na barra de navegação.
Ao lado do menu Projects, expanda o menu Options, clique em Project Settings e clique em Access Manager na barra lateral.
A página Project Access Manager (Gerente de acesso do projeto) é exibida.
Atribua funções do projeto à sua conta de serviço.
No menu que aparece, selecione a nova função ou funções da conta de serviço.
Você pode usar a API de administração do Atlas para conceder acesso a um projeto a uma conta de serviço existente.
Adicionar acesso ao projeto de um projeto
Se você ainda não criou chaves de API ou uma conta de serviço para uma organização, você pode criá-las para um projeto, a fim de conceder a esse projeto acesso à API de administração do Atlas. As chaves de API ou a conta de serviço que você cria para um projeto são automaticamente adicionadas à organização principal com a permissão Organization Member.
Para criar uma chave API para seu projeto utilizando o Atlas CLI, execute o seguinte comando:
atlas projects apiKeys create [options]
Para saber mais sobre a sintaxe e os parâmetros do comando, consulte a documentação do Atlas CLI para atlas organizations apiKeys create.
Depois de criar a chave de API do projeto, use a UI do Atlas para adicionar uma entrada na lista de acesso à API. Você não pode usar a chave de API no projeto até configurar a lista de acesso à API.
Observação
Limitação do Atlas CLI
Você não pode editar a lista de acesso à API da chave de API de um projeto usando o Atlas CLI.
Para adicionar uma entrada da lista de acesso de API usando a UI do Atlas:
Adicione uma API Access List Entry.
Clique em Add Access List Entry.
Insira um endereço de IP a partir do qual você deseja que o Atlas aceite solicitações de API para essa chave de API. Você também pode clicar em Use Current IP Address se o host que você está usando para acessar o Atlas também fizer solicitações de API usando essa chave de API.
Clique em Save.
Para criar uma chave API para um projeto usando a UI do Atlas:
No Atlas, acesse a página Project Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Execute uma das seguintes etapas:
Selecione Project Access no menu Access Manager na barra de navegação.
Ao lado do menu Projects, expanda o menu Options, clique em Project Settings e clique em Access Manager na barra lateral.
A página Project Access Manager (Gerente de acesso do projeto) é exibida.
Insira o API Key Information.
Na página Create API Key:
Insira um Description.
No menu Project Permissions, selecione a nova função ou funções para a chave de API.
Adicione uma API Access List Entry.
Clique em Add Access List Entry.
Insira um endereço de IP a partir do qual você deseja que o Atlas aceite solicitações de API para essa chave de API.
Você também pode clicar em Use Current IP Address se o host que você está usando para acessar o Atlas também fizer solicitações de API usando essa chave de API.
Clique em Save.
Para criar uma conta de serviço para um projeto usando a IU do Atlas:
No Atlas, acesse a página Project Access Manager.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Execute uma das seguintes etapas:
Selecione Project Access no menu Access Manager na barra de navegação.
Ao lado do menu Projects, expanda o menu Options, clique em Project Settings e clique em Access Manager na barra lateral.
A página Project Access Manager (Gerente de acesso do projeto) é exibida.
Insira as informações da conta de serviço.
Insira um Name.
Insira um Description.
Selecione uma duração no menu Client Secret Expiration.
No menu Permissões do projeto, selecione a nova função ou funções da conta de serviço.
Adicione uma API Access List Entry.
Clique em Add Access List Entry.
Insira um endereço IP ou bloco CIDR do qual você deseja que o Atlas aceite solicitações de API para esta conta de serviço.
Você também pode clicar em Use Current IP Address se o host que você está usando para acessar o Atlas também fizer solicitações de API usando esta conta de serviço.
Clique em Save.
Você pode usar a API de administração do Atlas para criar uma conta de serviço para seu projeto.
Depois de criar a conta de serviço, copie e salve o {CLIENT-ID} e o {CLIENT-SECRET} do resultado, que deve ser semelhante ao exemplo a seguir. Esse é o único momento em que você pode visualizar o segredo completo do cliente. Você precisará dessas informações quando fizer uma solicitação de API.
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
Solicitação API: como fazer
A API de administração do Atlas usa um dos dois métodos de autenticação para autenticar solicitações: chaves de API ou uma conta de serviço. Você precisará das chaves ou do segredo que salvou ao configurar o método de autenticação preferido para concluir os procedimentos a seguir.
Importante
No momento, as contas de serviço estão em prévia. Para saber mais, consulte Visão geral das contas de serviço.
Todos os endpoints do Atlas Administration API têm a seguinte URL base:
https://cloud.mongodb.com/api/atlas/<version>
Sua solicitação deve se parecer com os exemplos a seguir, em que {PUBLIC-KEY} é a chave pública da API e {PRIVATE-KEY} é a chave privada correspondente. Para explorar os endpoints disponíveis por meio da API de administração do Atlas, você pode usar o espaço de trabalho do Postman do MongoDB.
A seguinte amostra de solicitação GET retorna todos os projetos na sua organização:
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
A seguinte amostra de solicitação POST recebe um corpo da solicitação e cria um projeto denominado MyProject na sua organização:
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
Para fazer uma solicitação de API usando uma conta de serviço, use a conta de serviço para gerar um token de acesso e, em seguida, use o token de acesso em sua solicitação:
Recupere o segredo do cliente para sua conta de serviço.
Localize o segredo do cliente que começa com mdb_sa_sk_ que você salvou imediatamente após criar a conta de serviço, que foi a única vez que você pôde visualizar o segredo do cliente. Se você não salvou o segredo do cliente, deve gerar um novo.
Solicitar um token de acesso.
Substitua {BASE64-AUTH} no exemplo a seguir pela saída da etapa anterior e execute:
1 curl --request POST \ 2 --url https://cloud.mongodb.com/api/oauth/token \ 3 --header 'accept: application/json' \ 4 --header 'cache-control: no-cache' \ 5 --header 'authorization: Basic {BASE64-AUTH}' \ 6 --header 'content-type: application/x-www-form-urlencoded' \ 7 --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%
Importante
O token de acesso é válido por 1 hora (3600 segundos). Você não pode atualizar um token de acesso. Quando esse token de acesso expirar, repita essa etapa para gerar um novo.
Faça uma chamada de API.
Substitua {ACCESS-TOKEN} no exemplo a seguir pela saída da etapa anterior.
A seguinte amostra de solicitação GET retorna todos os projetos na sua organização:
curl --request GET \ --url https://cloud.mongodb.com/api/atlas/v2/groups \ --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header 'Accept: application/vnd.atlas.2023-02-01+json' \ --header 'Content-Type: application/json'
A seguinte amostra de solicitação POST recebe um corpo da solicitação e cria um projeto denominado MyProject na sua organização:
curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2023-02-01+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
Dica
Veja também:
Alternativamente, você pode usar qualquer ferramenta que suporte a especificação OpenAPI v3 para gerar exemplos de código ou servidores de simulação. Por exemplo, você pode importar a Especificação da API Admin do Atlas para o Postman para gerar comandos curl. Para usar o Postman para gerar comandos curl:
Na documentação da API de Administração do MongoDB Atlas, clique com o botão direito em Baixar e copie o link.
Próximos passos
Para saber mais sobre a API de Administração do Atlas, consulte Referência da API de administração do Atlas.
Para gerenciar o acesso de programação à API de administração do Atlas, consulte qualquer um dos seguintes procedimentos: