Your AI Connector Docs

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

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

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: 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

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

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

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

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

Â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 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:

{
  "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"
}

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.
  • 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.
  • Utilize sempre HTTPS para que a chave seja encriptada durante o trânsito.

Próximos passos