# Autenticação Cada pedido à API deve conter a sua chave de API para que o Your AI Connector saiba quem é e sobre que conta deve atuar. Pode enviar a chave de quatro formas diferentes — todas funcionam em qualquer endpoint que aceite autenticação por chave de API, por isso escolha a que melhor se adapta à sua configuração. O acesso à API é uma funcionalidade paga. Se o seu plano não a incluir, os pedidos são rejeitados com um `403`, mesmo que a chave seja válida — consulte [A restrição de funcionalidade paga](#the-paid-feature-gate) abaixo. Para gerar uma chave, consulte [Acesso à API](../integrations/api-access.md). > **Apenas HTTPS.** Todos os pedidos devem utilizar uma ligação segura. Pedidos HTTP simples são rejeitados antes mesmo de a autenticação ser processada. --- ## Visão geral dos quatro métodos | Método | Transportador | Quando utilizar | |---|---|---| | 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 Firebase | `Authorization: Bearer ` | Apenas sessões de aplicações próprias | Quando mais do que um está presente, o parâmetro de consulta tem prioridade, seguido do cabeçalho `X-API-Key` e, por fim, do token bearer. Na prática, envia apenas um. --- ## 1. Parâmetro de consulta — `?apiKey=` Adicione a sua chave ao final do endereço web. Esta é a forma mais simples e funciona sempre, o que a torna ideal para testes rápidos, scripts e ferramentas mais antigas. **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:** Os endereços web ficam registados no histórico do navegador, nos registos de acesso do servidor e nos registos de proxy. Para qualquer situação que não seja um teste rápido, prefira um dos métodos de cabeçalho abaixo para que a sua chave não seja escrita em disco de forma visível. --- ## 2. Cabeçalho `X-API-Key` Envie a chave num cabeçalho dedicado. Isto mantém-na fora do 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` Também pode transmitir a chave como um token de portador (bearer token) padrão. Isto é útil quando o seu cliente ou framework HTTP já tem 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 distingue automaticamente a sua chave de API de um token de início de sessão, pelo que este método funciona exatamente como o `X-API-Key`. --- ## 4. Token de ID do Firebase (apenas para aplicações próprias) Se estiver a criar uma aplicação própria que autentica utilizadores através do início de sessão do próprio Your AI Connector, pode transmitir o token de ID do Firebase desse utilizador autenticado como um token de portador em vez de uma chave de API: ``` Authorization: Bearer ``` O token é verificado em cada pedido e mapeado para a conta com sessão iniciada. **Este método destina-se apenas a sessões de aplicações próprias** — não pode gerar estes tokens a partir de uma integração externa e não existe forma de obter um sem passar pelo processo normal de início de sessão da aplicação. Para integrações servidor-a-servidor e de terceiros, utilize uma chave de API (métodos 1–3). --- ## Quando utilizar cada um - **Testes rápidos e scripts pontuais** → parâmetro de consulta (`?apiKey=`). Mais rápido de escrever, funciona num browser. - **Integrações de produção e chamadas servidor-a-servidor** → `X-API-Key` ou `Authorization: Bearer YOUR_API_KEY`. Mantém a chave fora dos URLs e dos registos. - **Aplicações próprias com um utilizador Your AI Connector autenticado** → `Authorization: Bearer `. --- ## Âmbitos das chaves A sua conta tem uma **chave de API principal** — aquela que se encontra em **Definições → Integrações → Chave de API**. Esta tem acesso total a tudo o que a conta pode fazer. Também pode criar **chaves com âmbito definido** adicionais: chaves com nome que apenas acedem às partes da API que escolher, por exemplo, uma chave de leitura limitada a Analytics para um painel de relatórios. Uma chave com âmbito definido é enviada exatamente da mesma forma que a chave principal (qualquer um dos métodos 1–3 acima), mas é verificada em relação às suas próprias permissões em cada pedido: - **Fora das suas áreas permitidas, é recusada.** Uma escrita com uma chave de leitura, ou uma chamada para uma secção que não foi atribuída à chave, devolve `403` — `key_read_only` ou `key_scope_denied` no campo `error_code`. A verificação é deliberadamente rigorosa: tudo o que não esteja claramente dentro das áreas permitidas da chave é recusado em vez de ser aceite, por isso, se vir um desses `403`, a chave simplesmente não cobre esse endpoint. - **Tem o seu próprio orçamento de limite de taxa.** Uma chave com âmbito definido é contabilizada separadamente da sua chave principal, pelo que um painel de controlo ocupado que utilize uma chave com âmbito definido não pode esgotar a quota de que dependem as suas outras integrações. Escolhe esse orçamento por minuto quando cria a chave. - **Não pode gerir chaves de API.** Apenas o proprietário da conta — com sessão iniciada ou utilizando a chave principal — pode listar, criar, editar, rodar ou revogar chaves. Uma chave com âmbito definido nunca pode criar uma chave com mais permissões. Consulte [Chaves de API](api-keys.md) para saber como criar, editar e revogar chaves com âmbito definido. --- ## O controlo de funcionalidades pagas O acesso à API é uma funcionalidade paga. Quando o seu plano não a inclui, um pedido com uma chave que seria válida é rejeitado 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" } ``` --- ## Manter a sua chave segura - **Trate a chave como uma palavra-passe.** A sua chave principal concede acesso total à sua conta. Se precisar de entregar uma chave a uma ferramenta ou a uma pessoa que apenas necessita de parte dela, crie antes uma chave com âmbito definido — consulte [Âmbitos das chaves](#key-scopes). - **Mantenha-a no lado do servidor.** Nunca a incorpore em JavaScript de browser, num pacote de aplicação móvel ou em qualquer código que um utilizador final possa ler. - **Armazene-a num gestor de segredos** ou na configuração do lado do servidor, não no controlo de código-fonte. - **Rode-a se houver uma fuga.** Gere uma nova chave a partir do painel de controlo ou chame `POST https://api.youraiconnector.com/v1/api-keys/rotate` — isto invalida imediatamente a antiga. Consulte [Chaves de API](api-keys.md). - **Utilize sempre HTTPS** para que a chave seja encriptada durante o trânsito. --- ## Próximos passos - [Introdução](getting-started.md) — o seu primeiro pedido e os guias de recursos. - [Erros e Paginação](errors-and-pagination.md) — lide com falhas e percorra os resultados. - [Chaves de API](api-keys.md) — rode, revogue e verifique a utilização da sua chave.