Your AI Connector Docs

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 abaixo. Para gerar uma chave, consulte Acesso à API.

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 <ID token> 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

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

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

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

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

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

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 <Firebase ID token>

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 <Firebase ID token>.

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 403s, 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 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:

{
  "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. A missing or wrong key returns 401 instead:

{
  "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.
  • 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.
  • Sempre use HTTPS para que a chave seja criptografada em trânsito.

Próximos passos