# Autenticação Cada solicitação de API deve conter sua chave de API para que o Your AI Connector saiba quem é você e em qual conta deve atuar. Você pode enviar a chave de quatro maneiras diferentes — todas funcionam em qualquer endpoint que aceite autenticação por chave de API, então escolha a que melhor se adapta à sua configuração. O acesso à API é um recurso pago. Se o seu plano não o incluir, as solicitações serão rejeitadas com um `403`, mesmo que a chave em si seja válida — consulte [O bloqueio de recursos pagos](#the-paid-feature-gate) abaixo. Para gerar uma chave, consulte [Acesso à API](../integrations/api-access.md). > **Apenas HTTPS.** Todas as solicitações devem usar uma conexão segura. Solicitações HTTP simples são rejeitadas antes mesmo que a autenticação seja executada. --- ## Visão geral dos quatro métodos | Método | Transportador | Quando usar | |---|---|---| | Parâmetro de consulta | `?apiKey=YOUR_API_KEY` | Testes rápidos e URLs de navegador | | Cabeçalho | `X-API-Key: YOUR_API_KEY` | Integrações de produção | | Cabeçalho Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrações de produção | | Token de ID do Firebase | `Authorization: Bearer ` | Apenas sessões de aplicativos de primeira parte | Quando mais de um estiver presente, o parâmetro de consulta prevalece, seguido pelo cabeçalho `X-API-Key` e, por fim, pelo token bearer. Na prática, você enviará apenas um. --- ## 1. Parâmetro de consulta — `?apiKey=` Adicione sua chave ao final do endereço da web. Esta é a forma mais simples e sempre funciona, o que a torna ideal para testes rápidos, scripts e qualquer ferramenta mais antiga. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", params={"apiKey": "YOUR_API_KEY"}, ) data = res.json() ``` > **Atenção:** Endereços da web acabam no histórico do navegador, nos logs de acesso do servidor e nos logs de proxy. Para qualquer coisa além de um teste rápido, prefira um dos métodos de cabeçalho abaixo para que sua chave não seja gravada em disco de forma legível. --- ## 2. Cabeçalho `X-API-Key` Envie a chave em um cabeçalho dedicado. Isso a mantém fora da URL e é a escolha recomendada para produção. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` --- ## 3. Cabeçalho `Authorization: Bearer` Você também pode passar a chave como um bearer token padrão. Isso é útil quando seu cliente ou framework HTTP já possui suporte integrado para cabeçalhos `Authorization`. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { Authorization: "Bearer YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) data = res.json() ``` A API diferencia automaticamente sua chave de API de um token de login, portanto, este método funciona exatamente como o `X-API-Key`. --- ## 4. Token de ID do Firebase (apenas para aplicações proprietárias) Se você estiver criando um aplicativo proprietário que autentica usuários por meio do próprio login do Your AI Connector, você pode passar o token de ID do Firebase desse usuário autenticado como um bearer token em vez de uma chave de API: ``` Authorization: Bearer ``` O token é verificado em cada solicitação e mapeado para a conta autenticada. **Este método é apenas para sessões de aplicativos proprietários** — você não pode gerar esses tokens a partir de uma integração externa, e não há como obter um sem passar pelo login normal do aplicativo. Para integrações servidor-a-servidor e de terceiros, use uma chave de API (métodos 1–3). --- ## Quando usar cada um - **Testes rápidos e scripts únicos** → parâmetro de consulta (`?apiKey=`). Mais rápido de digitar, funciona no navegador. - **Integrações em produção e chamadas servidor-a-servidor** → `X-API-Key` ou `Authorization: Bearer YOUR_API_KEY`. Mantém a chave fora de URLs e logs. - **Aplicativos proprietários com um usuário Your AI Connector logado** → `Authorization: Bearer `. --- ## Escopos de chave Sua conta possui uma **chave de API principal** — aquela em **Configurações → Integrações → Chave de API**. Ela tem acesso total a tudo o que a conta pode fazer. Você também pode criar **chaves com escopo**: chaves nomeadas que alcançam apenas as partes da API que você escolher, por exemplo, uma chave somente leitura limitada a Analytics para um painel de relatórios. Uma chave com escopo é enviada exatamente como a chave principal (qualquer um dos métodos 1–3 acima), mas é verificada em relação às suas próprias permissões em cada solicitação: - **Fora de suas áreas permitidas, ela é recusada.** Uma gravação com uma chave somente leitura, ou uma chamada para uma seção que a chave não recebeu, retorna como `403` — `key_read_only` ou `key_scope_denied` no campo `error_code`. A verificação é deliberadamente rigorosa: tudo o que não estiver claramente dentro das áreas permitidas da chave é recusado em vez de ser permitido, portanto, se você vir um desses `403`s, a chave simplesmente não cobre esse endpoint. - **Ela tem seu próprio orçamento de limite de taxa.** Uma chave com escopo é contada separadamente da sua chave principal, para que um painel ocupado usando uma chave com escopo não possa esgotar a permissão da qual suas outras integrações dependem. Você escolhe esse orçamento por minuto ao criar a chave. - **Ela não pode gerenciar chaves de API.** Somente o proprietário da conta — conectado ou usando a chave principal — pode listar, criar, editar, rotacionar ou revogar chaves. Uma chave com escopo nunca pode criar uma chave mais abrangente para si mesma. Consulte [Chaves de API](api-keys.md) para saber como criar, editar e revogar chaves com escopo. --- ## O bloqueio de recursos pagos O acesso à API é um recurso pago. Quando seu plano não o inclui, uma solicitação com uma chave válida é rejeitada com `403`: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` If you see this, check your plan or contact [hi@youraiconnector.com](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead: ```json { "success": false, "error_code": 401, "error": "Invalid API key" } ``` --- ## Mantendo sua chave segura - **Trate a chave como uma senha.** Sua chave principal concede acesso total à sua conta. Se você precisar entregar uma chave a uma ferramenta ou pessoa que só precisa de parte dela, crie uma chave com escopo — consulte [Escopos de chave](#key-scopes). - **Mantenha-a no lado do servidor.** Nunca a incorpore em JavaScript de navegador, em um pacote de aplicativo móvel ou em qualquer código que um usuário final possa ler. - **Armazene-a em um gerenciador de segredos** ou na configuração do lado do servidor, não no controle de código-fonte. - **Rotacione-a se houver vazamento.** Gere uma nova chave no painel ou chame `POST https://api.youraiconnector.com/v1/api-keys/rotate` — isso invalida imediatamente a antiga. Consulte [Chaves de API](api-keys.md). - **Sempre use HTTPS** para que a chave seja criptografada em trânsito. --- ## Próximos passos - [Introdução](getting-started.md) — sua primeira solicitação e os guias de recursos. - [Erros e Paginação](errors-and-pagination.md) — lide com falhas e pagine os resultados. - [Chaves de API](api-keys.md) — rotacione, revogue e verifique o uso da sua chave.