Criando uma Chave API

Chamados de API da Megaport exigem um token de acesso que você pode gerar após criar uma chave API. Esse token é necessário para autenticar usuários API, e permite acesso temporário apenas às partes do Megaport Portal que são necessárias.

Recomenda-se que uma conta de admin da empresa machine to machine (M2M) seja criada para acessar o API da Megaport e criar as chaves API. No caso de um usuário humano ser desativado ou ficar trancado para fora de sua conta, as chaves API criadas por esse usuário também serão suspensas, o que pode interromper o funcionamento de quaisquer integrações via API.

Chaves API são válidas apenas no ambiente em que foram geradas. Se você precisar de chaves API para acessar um ambiente diferente, faça login no Megaport Portal naquele ambiente e gere as chaves por lá.

Aviso

Você deve estar logado no Megaport Portal como um usuário com o papel de Admin da Empresa para criar uma chave API. Para mais informações, veja Gerenciando Papeis de Usuários.
No máximo cinco chaves API podem ser criadas por empresa.

Este tópico descreve as seguintes tarefas:

Criar uma chave API no Megaport Portal
Gerar um token de acesso no Postman

Criar uma chave API no Megaport Portal

No Megaport Portal, selecione Ferramentas > Gerador de Chaves API.
A tela de Chaves API permite que você crie chaves, e veja e edite chaves API existentes.
Especifique os detalhes da chave APISpecify the details for the API key.
- Nome – Insira um nome para a chave API.
  Este deve ser um nome descritivo para identificar o propósito da chave.
  Aviso
  - No mínimo três caracteres são necessários para o nome da chave API.
  - Não são permitidos caracteres especiais, com exceção de travessões e hífen..
- Papel – Escolha o papel do usuário que usará a API.
  Estão disponíveis as seguintes opções:
  - Admin da Empresa
  - Apenas Leitura
- Validade do Token (Minutos) – Insira o período de tempo (em minutos) após o qual o token gerado a partir dessa chave expirará. O mínimo é cinco minutos e o máximo é 24 horas (1440 minutos). Depois que o token expirar, você deverá gerar um novo token de acesso.
Clique em Gerar Chave.
A chave API é criada e a janela Sua Chave API aparece.

Importante

Copie a sua nova Chave API e o seu Segredo da Chave API, e guarde essas credenciais em algum lugar seguro. Você precisará usá-las para gerar tokens de acesso. Certifique-se de copiar o Segredo da Chave API porque ele não será mostrado novamente após o fechamento da janela.
Clique em Copiar à direita do campo Chave API e cole a chave (ID do Cliente) num local seguro.
Clique em Copiar à direita do campo Segredo da Chave API e cole o Cliente em um local seguro.
Clique em Fechar.
A chave API será criada e mostrada na área Chaves API Ativas da tela.
Na área Chaves API Ativas, você pode editar o nome da chave, deletá-la, e ver o histórico de mudanças que ocorreram para aquela chave.

Gerando um token de acesso

Após ter criado a chave API, que consiste num ID do cliente e um segredo do cliente, você pode gerar um token de acesso para autenticar usuários API. Estas instruções descrevem como você pode fazer isso usando o Postman e a coleção da Megaport. Para detalhes de configurações do Postman, veja API da Megaport.

A URL de solicitação que você precisa usar depende do ambiente em que você estiver gerando um token de acesso. Em cada ambiente, essas URLs de solicitação devem ser usadas:

Ambiente de Produção – https://auth-m2m.megaport.com/oauth2/token
Ambiente de Teste (staging) – https://oauth-m2m-staging.auth.ap-southeast-2.amazoncognito.com/oauth2/token

Estas instruções descrevem como gerar um token de acesso no ambiente de Produção. Para mais informações, veja API da Megaport e Autenticação da Megaport - Chaves API.

Aviso

Quais endpoints da API um token de acesso pode chamar depende do papel selecionado para a chave API quando ela foi criada. Por exemplo: Chaves API Apenas Leitura terão mais restrições quanto aos dados que podem ser acessados do que chaves API Admins da Empresa.

Gerar um token de acesso no Postman

Na coleção da Megaport importada no Postman, clique no ícone de “mais” para adicionar uma solicitação nova.
Na lista de seleção à esquerda do campo Solicite URL, selecione POST.
No campo Solicite URL, insira a seguinte URL de solicitação:
https://auth-m2m.megaport.com/oauth2/token
Selecione a aba Authorization e insira os seguintes detalhes de parâmetros:
- Username – O ID de Cliente que você copiou mais cedo ao criar a chave API.
- Password – O segredo de Cliente que você copiou mais cedo ao criar a chave API.
Aviso

Esses parâmetros contém dados sensíveis. Se você estiver trabalhando em um ambiente colaborativo, pode ser interessante definir o ID de cliente e o segredo de cliente como as variáveis {{apiKeyClientId}} e {{apiKeyClientSecret}} respectivamente. Para mais informações sobre variáveis, veja a documentação do Postman.
Clique na aba Body e insira uma chave chamada grant_type que esará definida como o valor client_credentials.
Clique em Save.
A tela de Salvar solicitação aparecerá.
No campoRequest name, insira um nome significativo para a nova solicitação.
Por exemplo, Gerar Token de Acesso.
(Opcional) Insira uma descrição da solicitação.
Escolha onde você gostaria de salvar a solicitação e então clique em Save.
A nova solicitação será criada e adicionada à coleção de Documentação da API da Megaport.
Clique em Enviar.

Você deve receber uma resposta que inclui o seu token de acesso, semelhante ao exemplo abaixo. Uma vez que um token de acesso for gerado, ele pode ser usado para autenticar usuários API para vários endpoints no Megaport Portal.
```
 {
  "access_token":  
      "eyJraWQ......2cOQGA",
  "expires_in": 86400,
  "token_type": "Bearer"
 }
```
Copie o token de acesso.
Nas variáveis da coleção (clique nos três pontos depois da coleção da Megaport importada > Edit > Variables), adicione uma entrada para access_token e cole o token de acesso no campo VALOR ATUAL.
Para cada chamada API que você precisar enviar, na aba Authorization, o Type deve ser definido como Bearer Token e o Token deve ser definido como a variável de token de acesso {{access_token}}.

A chamada de API agora está pronta para ser usada. Todas as chamadas de API são feitas por SSL/TLS, e cada chamada é validada contra o token de acesso para as permissões apropriadas.

Aviso

Tokens de acesso expiram, então você precisará gerar novos tokens regularmente para as suas chamadas de API. O período de expiração é determinado pelo valor que foi inserido no capo Validade do Token (Minutos) quando a chave API foi criada. O período padrão de validade é 24 horas.

Solicitações API incluem dois importantes parâmetros de header: Authorization e Content-Type. O parâmetro Authorization aponta para a aba Authorization onde a variável do token está definida.

Cabeçalhos obrigatórios

cURL token generation

Outro jeito de gerar um token de acesso é usando o cURL a partir de um console de comando no seguinte formato:

 curl -X "POST" "https://auth-m2m.megaport.com/oauth2/token" \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -u 'value_of_base64(clientId:clientSecret)_here' \
        --data-urlencode "grant_type=client_credentials"

Dica

O site dev.megaport.com permite que você veja cada endpoint API em múltiplas linguagens de programação.