Vídeo: confira este vídeo curto para ver como proteger sua API.
O que você aprenderá
Neste tutorial, explicamos como:
Criar um proxy de API que exija uma chave de API.
Criar um produto de API, um desenvolvedor e um aplicativo de desenvolvedor.
Chamar a API com uma chave de API.
É importante proteger a API contra acesso não autorizado. Uma maneira de fazer isso é com
chaves de API.
Quando um app faz uma solicitação a um proxy de API configurado para verificar uma chave de API,
ele precisa fornecer uma chave válida. No ambiente de execução,
a política "Verificar chave de API" verifica se a chave de API fornecida:
É válido
Não foi revogada
Corresponde à chave de API do produto de API que expõe os recursos solicitados
Se a chave for válida, a solicitação será permitida. Se a chave for inválida, a solicitação resultará em
uma falha de autorização.
Selecione a organização usando o menu suspenso no canto superior esquerdo da IU.
Clique em Desenvolver > Proxies de API para exibir a lista de
proxies de API.
Clique em Criar nova.
No assistente de criação de proxy, selecione Proxy reverso (mais comum).
Configure o proxy da seguinte maneira:
Neste campo
faça isso
Nome do proxy
Insira: helloworld_apikey
Caminho base do projeto
Altere para: /helloapikey
O caminho base do projeto faz parte do URL usado para fazer solicitações ao proxy
da API.
Descrição
Insira: hello world protected by API key
Destino (API existente)
Insira: http://mocktarget.apigee.net
Isso define o URL de destino que a Apigee invoca em uma solicitação ao proxy
de API. Esse destino retorna apenas uma resposta simples: Hello, Guest!.
Clique em Próxima.
Na página Políticas comuns, selecione Chave de API.
Esta opção adiciona automaticamente duas políticas ao
proxy de API e cria um produto de API necessário para gerar a chave de API.
Clique em Próxima.
Na página "Resumo", verifique se o ambiente de implantação está
selecionado e clique em Criar e implantar.
Clique em Editar proxy para exibir a
página Visão geral do proxy de API.
Ver as políticas
No editor de proxy da API, clique na guia Desenvolvedor. Você verá que duas
políticas foram adicionadas ao fluxo de solicitações do proxy da API:
Verificar a chave de API: verifica a chamada de API para garantir a presença de uma chave de API
válida (enviada como um parâmetro de consulta).
Remover apikey de consulta: uma política de atribuir mensagem que
remove a chave de API após a verificação, para que ela não seja transmitida e
exposta desnecessariamente.
Clique no ícone de política "Verificar chave de API" na visualização de fluxo e observe a configuração
XML da política na visualização de código mais baixa. O elemento <APIKey> informa à
política onde ele precisa procurar a chave de API quando a chamada é feita. Por padrão, ele procura
a chave como um parâmetro de consulta chamado apikey na solicitação HTTP:
<APIKey ref="request.queryparam.apikey" />
O nome apikey é arbitrário e pode ser qualquer propriedade que contenha a
chave de API.
Tentar chamar a API
Nesta etapa, você fará uma chamada de API bem-sucedida diretamente para o serviço de destino e
fará uma chamada sem sucesso para o proxy de API para ver como ela está sendo protegida pelas
políticas.
Sucesso
Em um navegador da Web, acesse o endereço a seguir. Este é o serviço de destino para o qual o proxy da
API está configurado para encaminhar a solicitação, mas você a alcançará diretamente por enquanto:
http://mocktarget.apigee.net
Você receberá esta resposta bem-sucedida: Hello, Guest!
Sem a política "Verificar chave de API", essa chamada daria a mesma resposta que
a chamada anterior. Nesse caso, você receberá a seguinte resposta de erro:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Isso significa que, corretamente, você não passou uma chave de API válida como um parâmetro
de consulta.
Nas próximas etapas, você receberá a chave de API necessária.
Como adicionar um produto de API
Para adicionar um produto de API usando a IU da Apigee:
Selecione Publicar > Produtos da API.
Clique em Criar.
Insira os detalhes do produto do produto de API.
Campo
Descrição
Nome
Nome interno do produto de API. Não especifique caracteres especiais no nome. Observação: não é possível editar o nome depois que o produto da API é criado.
Nome de exibição
Nome de exibição do produto de API. O nome de exibição é usado na IU e é possível editá-lo a qualquer momento. Se não for especificado, o valor Nome será usado. Esse campo é preenchido automaticamente com o valor do nome. você pode editar ou excluir o conteúdo. O nome de exibição pode incluir caracteres especiais.
Descrição
Descrição do produto de API.
Ambiente
Ambientes em que o produto de API permitirá acesso. Por exemplo, test ou prod.
Acesso
Selecione Público.
Aprovar automaticamente solicitações de acesso
Ativar a aprovação automática das solicitações de chave deste produto de API em qualquer app.
Cota
Ignorar para este tutorial.
Escopos do OAuth permitidos
Ignorar para este tutorial.
Na seção Operações, clique em ADICIONAR UMA OPERAÇÃO.
No campo "API Proxy", selecione o proxy de API que você acabou de criar.
No campo "Caminho", digite "/". Ignore os outros campos.
Clique em Salvar para salvar a operação.
Clique em Salvar para salvar o produto da API.
Adicionar um desenvolvedor e um app à sua
organização
Em seguida, vamos simular o fluxo de trabalho de um desenvolvedor se inscrevendo para usar suas APIs. Um
desenvolvedor terá um ou mais apps que chamam suas APIs, e cada app recebe uma chave exclusiva.
Isso oferece a você, o provedor da API, um controle mais granular sobre o acesso às suas APIs e relatórios mais
detalhados sobre o tráfego da API por aplicativo.
Crie um desenvolvedor
Para criar um desenvolvedor:
Selecione Publicar > Desenvolvedores no menu. Observação: se você ainda estiver na tela "Desenvolver", clique em "<" por DESENVOLVER para exibir o menu e selecione Publicar > Desenvolvedores
Clique em + Desenvolvedor.
Digite o seguinte na janela "Novo desenvolvedor":
Neste campo
enter
Nome
Keyser
Sobrenome
Soze
Nome de usuário
keyser
E-mail
keyser@example.com
Clique em Criar.
Registrar um aplicativo
Para registrar um app de desenvolvedor:
Selecione Publicar > Apps.
Clique em + App.
Digite o seguinte na janela "Novo app de desenvolvedor":
Neste campo
faça isso
Nome e nome de exibição
Insira: keyser_app
Desenvolvedor
Selecione: Keyser Soze (keyser@example.com)
Callback URL e Observações
Deixar em branco
Na seção "Credenciais", selecione Nunca.
As credenciais deste aplicativo nunca expirarão.
Clique em Adicionar produto.
Selecione o produto que você acabou de criar.
Clique em Criar.
Encontre a chave de API
Para acessar a chave de API, faça o seguinte:
Na página "Apps" (Publicar > Apps), clique em keyser_app.
Na página keyser_app, clique em Mostrar ao lado de Chave na seção
Credenciais. A chave está associada ao produto que você criou.
Selecione e copie a chave. Ela será usada na próxima etapa.
Chamar a API com uma chave
Agora que você tem uma chave de API, pode usá-la para chamar o proxy de API. Cole a chave de API conforme
mostrado, como um parâmetro de consulta. Verifique se não há espaços
extras no parâmetro de consulta.
Agora, ao chamar o proxy de API, você receberá esta resposta: Hello,
Guest!
Parabéns! Você criou um proxy de API e o protegeu exigindo que uma chave de
API válida fosse incluída na chamada.
Em geral, não é uma boa prática passar uma chave de API como um parâmetro de consulta. Considere
passá-la no cabeçalho
HTTP.
Prática recomendada: passar a chave no cabeçalho
HTTP
Nesta etapa, você modificará o proxy para procurar a chave de API em um cabeçalho chamado x-apikey.
Edite o proxy de API. Selecione Desenvolver > Proxies de API >
helloworld_apikey e acesse a visualização Desenvolver.
Selecione a política Verificar chave de API e modifique o XML da política para
permitir que a política procure no header e não no
queryparam:
<APIKey ref="request.header.x-apikey"/>
Salve o proxy de API e selecione Implantar.
Faça a seguinte chamada de API usando cURL para transmitir a chave de API como um cabeçalho chamado
x-apikey. Não se esqueça de substituir o nome da sua organização.
Para concluir a alteração, você também precisa configurar a política
"Atribuir mensagem" para remover o cabeçalho em vez do parâmetro de consulta. Por exemplo:
A proteção de APIs geralmente envolve mais segurança, como o OAuth, um
protocolo aberto que troca credenciais (como nome de usuário e senha) para
tokens de acesso. Os tokens de acesso são strings longas e aleatórias que podem ser transmitidas por um pipeline
de mensagem, mesmo de um app para outro, sem comprometer as credenciais originais.
Para uma visão geral dos tópicos relacionados à segurança, consulte
Como proteger um proxy.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[[["\u003cp\u003eThis guide demonstrates how to secure APIs in Apigee and Apigee hybrid using API keys to prevent unauthorized access.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial walks through the process of creating an API proxy, configuring it to require API keys, and setting up policies to verify and remove the API key.\u003c/p\u003e\n"],["\u003cp\u003eIt explains how to create API products, developers, and developer apps, which are needed to generate API keys for accessing the protected API proxy.\u003c/p\u003e\n"],["\u003cp\u003eThe document illustrates how to test the API proxy by making calls with and without a valid API key, showcasing the security enforcement.\u003c/p\u003e\n"],["\u003cp\u003eIt highlights the best practice of passing API keys in the HTTP header (x-apikey) instead of as a query parameter for enhanced security, and details the required modifications to the API proxy.\u003c/p\u003e\n"]]],[],null,["# Secure an API by requiring API keys\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n| **Note:** This video was recorded with a previous version of the Apigee UI; however, the concepts are still valid.\n\n\n**Video:** Check out this short video for an introduction on securing your API. \n**What you'll learn**\n\nThis tutorial explains how to:\n\n- Create an API proxy that requires an API key.\n- Create an API product, a developer, and a developer app.\n- Call your API with an API key. \nIt's important to protect your API from unauthorized access. One way to do that is with\nAPI keys.\n\nWhen an app makes a request to an API proxy that is configured to verify an API\nkey, the app must supply a valid key. At runtime, the\nVerify API Key policy checks that the supplied API key:\n\n- Is valid\n- Hasn't been revoked\n- Matches the API key for the API product that exposes the requested resources\n\nIf the key is valid, the request is allowed. If the key is invalid, the request results in\nan authorization failure. \n\nCreate the API proxy\n--------------------\n\n1. Go to the [Apigee UI](https://apigee.google.com) and sign in.\n2. Select your organization using the drop-down menu in the upper left corner of the UI.\n3. Click **Develop \\\u003e API Proxies** to display the API\n proxies list.\n\n4. Click **Create New** . \n5. In the Build a Proxy wizard, select **Reverse proxy (most common)**.\n6. Configure the proxy as follows: \n\n7. Click **Next**.\n8. On the **Common policies** page, select **API Key**. This option automatically adds two policies to your API proxy and creates an API product needed for generating the API key.\n9. Click **Next**.\n10. On the Summary page, make sure a deployment environment is selected, and click **Create and deploy**.\n11. Click **Edit proxy** to display the Overview page for the API proxy. \n\nView the policies\n-----------------\n\n1. In the API proxy editor, click the **Develop** tab. You'll see that two policies have been added to the request flow of the API proxy:\n - **Verify API Key** -- Checks the API call to make sure a valid API key is present (sent as a query parameter).\n - **Remove Query Param apikey** -- An Assign Message policy that removes the API key after it's checked, so that it doesn't get passed around and exposed unnecessarily.\n2. Click the Verify API Key policy icon in the flow view, and look at the policy's XML\n configuration in the lower code view. The `\u003cAPIKey\u003e` element tells the\n policy where it should look for the API key when the call is made. By default, it looks\n for the key as a query parameter called `apikey` in the HTTP request:\n\n ```text\n \u003cAPIKey ref=\"request.queryparam.apikey\" /\u003e\n ```\n\n The name `apikey` is arbitrary and can be any property that contains the\nAPI key. \n\nTry to call the API\n-------------------\n\nIn this step, you'll make a successful API call directly to the target service, then\nyou'll make an unsuccessful call to the API proxy to see how it's being protected by the\npolicies.\n\n1. **Success**\n\n In a web browser, go to the following address. This is the target service that the API\n proxy is configured to forward the request to, but you'll hit it directly for now: \n\n ```text\n http://mocktarget.apigee.net\n ```\n\n You should get this successful response: `Hello, Guest!`\n2. **Failure**\n\n Now try to call your API proxy: \n\n ```\n curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\n where \u003cvar translate=\"no\"\u003eYOUR ENV_GROUP_HOSTNAME\u003c/var\u003e is the environment group hostname. See\n [Find the environment group hostname](/apigee/docs/api-platform/get-started/test-proxy#find-the-environment-group-hostname).\n | **Note:** If you have trouble calling the proxy, you may need to add the `Host` header, as described in [Deploy a sample proxy](/apigee/docs/api-platform/get-started/deploy-sample).\n\n Without the Verify API Key policy, this call would give you the same response as the\n previous call. But in this case, you should get the following error response: \n\n ```gdscript\n {\"fault\":{\"faultstring\":\"Failed to resolve API Key variable request.queryparam.apikey\",\"detail\":{\"errorcode\":\"steps.oauth.v2.FailedToResolveAPIKey\"}}}\n ```\n\n which means, correctly, that you didn't pass a valid API key (as a query\n parameter).\n\nIn the next steps, you'll get the required API key. \n\nAdding an API product\n---------------------\n\nTo add an API product using the Apigee UI:\n\n1. Select **Publish \\\u003e API Products**.\n2. Click **+Create**.\n3. Enter the Product Details for your API product. \n\n4. In the **Operations** section, click **ADD AN OPERATION**.\n5. In the API Proxy field, select the API proxy you just created.\n6. In the Path field, enter \"/\". Ignore the other fields.\n7. Click **Save** to save the Operation.\n8. Click **Save** to save the API product. \n\nAdd a developer and app to your\norganization\n--------------------------------------------\n\nNext, we're going to simulate the workflow of a developer signing up to use your APIs. A\ndeveloper will have one or more apps that call your APIs, and each app gets a unique API key.\nThis gives you, the API provider, more granular control over access to your APIs and more\ngranular reporting on API traffic by app.\n\n### Create a developer\n\nTo create a developer:\n\n1. Select **Publish \\\u003e Developers** in the menu. \n **Note** : If you are still in the Develop screen, click on the **\"\\\u003c\"** by **DEVELOP** to display the menu and select **Publish \\\u003e Developers**\n2. Click **+ Developer**.\n3. Enter the following in the New Developer window: \n\n4. Click **Create**.\n\n### Register an app\n\nTo register a developer app:\n\n1. Select **Publish \\\u003e Apps**.\n2. Click **+ App**.\n3. Enter the following in the New Developer App window: \n\n4. In the Credentials section, select **Never**. The credentials for this app will never expire.\n5. Click **Add product**.\n6. Select the product you just created.\n7. Click **Create**.\n\n### Get the API key\n\nTo get the API key:\n\n1. On the Apps page (Publish \\\u003e Apps), click **keyser_app**.\n2. On the **keyser_app** page, click **Show** next to **Key** in the **Credentials** section. Notice that the key is associated with the product you created. \n3. Select and copy the key. You'll use it in the next step. \n\nCall the API with a key\n-----------------------\n\nNow that you have an API key, you can use it to call the API proxy. Paste the API key as\nshown, as a query parameter. Make sure there are no extra\nspaces in the query parameter. \n\n```\ncurl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key\n```\n\nNow when you call the API proxy, you should get this response: `Hello,\nGuest!`\n\nCongratulations! You've created an API proxy and protected it by requiring that a valid\nAPI key be included in the call.\n\nNote that in general it's not good practice to pass an API key as a query parameter. You\nshould consider [passing it in the HTTP\nheader instead](#extracreditpassingthekeyinthehttpheader). \n\nBest practice: Passing the key in the HTTP\nheader\n-------------------------------------------------\n\n| **Note:** It's a good practice to pass the API key in a header rather than in a query parameter. Query parameters appear in the browser history and network logs, which could present a security risk. Headers do not appear in the browser history and network logs.\n\nIn this step, you will modify the proxy to look for the API key in a header called `x-apikey`.\n\n1. Edit the API proxy. Select **Develop \\\u003e API Proxies \\\u003e\n helloworld_apikey** , and go to the **Develop** view.\n2. Select the **Verify API Key** policy, and modify the policy XML to tell\n the policy to look in the `header` rather than in the\n `queryparam`:\n\n ```text\n \u003cAPIKey ref=\"request.header.x-apikey\"/\u003e\n ```\n3. **Save** the API proxy and use **Deploy** to deploy it.\n4. Make the following API call using cURL to pass the API key as a header called\n `x-apikey`. Don't forget to substitute your organization name.\n\n ```scdoc\n curl -v -H \"x-apikey: {api_key_goes_here}\" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\nNote that to fully complete the change, you'd also need to configure the Assign Message\npolicy to remove the header instead of the query parameter. For example: \n\n```\n\u003cRemove\u003e\n \u003cHeaders\u003e\n \u003cHeader name=\"x-apikey\"/\u003e\n \u003c/Headers\u003e\n\u003c/Remove\u003e\n```\n| **Note:** You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this: \n|\n| ```scdoc\n| \u003cAPIKey ref=\"request.formparam.{api_key_goes_here}\"/\u003e\n``` \n\nRelated topics\n--------------\n\nHere are some topics related to API products and keys:\n\n- [Managing API products](/apigee/docs/api-platform/publish/create-api-products)\n- [API keys](/apigee/docs/api-platform/security/api-keys)\n- [Registering app\n developers](/apigee/docs/api-platform/publish/adding-developers-your-api-product)\n- [Register apps and\n manage API keys](/apigee/docs/api-platform/publish/creating-apps-surface-your-api)\n- [Verify API Key\n policy](/apigee/docs/api-platform/reference/policies/verify-api-key-policy)\n\nAPI protection often involves additional security such as [OAuth](/apigee/docs/api-platform/security/oauth/oauth-home), an\nopen protocol that exchanges credentials (like username and password) for\naccess tokens. Access tokens are long, random strings that can be passed through a message\npipeline, including from app to app, without compromising the original credentials.\n\nFor an overview of security-related topics, see\n[Securing a proxy](https://cloud.google.com/apigee/docs/api-platform/security/api-security)."]]
