Documentazione

Autenticazione

Autentica le richieste API con token Bearer usando la tua chiave API.

Tutte le richieste API richiedono l'autenticazione tramite un token Bearer. Genera una chiave API dalla dashboard e includila nell'header Authorization.

Nota: l'accesso API richiede un piano Hobby o superiore con fatturazione attiva.

Genera una chiave API

  1. Vai alla dashboard del workspace del tuo team
  2. Clicca su Chiavi API nella barra laterale
  3. Clicca su Crea chiave API
  4. Copia la chiave generata

Usa la tua chiave API

Includi la chiave nell'header Authorization:

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chatbotId": "uuid", "messages": [{"role": "user", "content": "Hello"}]}'

Formato dell'header

Authorization: Bearer YOUR_API_KEY

Testa la tua chiave

Verifica che la tua chiave API funzioni con l'endpoint di autenticazione:

curl 'https://your-domain.com/api/v1/auth' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200):

{
  "id": "account-uuid",
  "name": "Your Workspace",
  "email": "[email protected]"
}

Chiave non valida (401):

{
  "message": "Missing or invalid Authorization header"
}

Sicurezza della chiave API

Best practice

  1. Non esporre mai le chiavi nel codice lato client - le chiavi API devono essere usate solo lato server
  2. Usa le variabili d'ambiente - evita di scrivere le chiavi direttamente (hardcoded) nel codice
  3. Ruota le chiavi periodicamente - elimina le chiavi vecchie e creane di nuove
  4. Usa nomi descrittivi - per sapere sempre quale chiave è usata dove

Formato della chiave

Le chiavi sono 32 byte casuali codificati in base64url.

Gestisci le chiavi API

Visualizza tutte le chiavi

Consulta tutte le chiavi in Workspace > Chiavi API.

Elimina le chiavi

Rimuovi le chiavi che non ti servono più:

  1. Vai su Chiavi API
  2. Trova la chiave
  3. Clicca su Elimina
  4. Conferma l'eliminazione

Le chiavi eliminate smettono di funzionare immediatamente.

Risposte di errore

StatoMessaggioCausa
401Missing or invalid Authorization headerHeader non fornito
401Invalid API keyChiave errata
403API access requires a Hobby plan or above with active billingLo stato del piano o della fatturazione non consente l'accesso API
403Chatbot does not belong to this accountL'ID dell'agente non appartiene all'account della chiave API

Configurazione dell'ambiente

Node.js

const API_KEY = process.env.AGENTKIT_API_KEY;

const response = await fetch('https://your-domain.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});

Python

import os
import requests

API_KEY = os.environ.get('AGENTKIT_API_KEY')

response = requests.post(
    'https://your-domain.com/api/v1/chat',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'chatbotId': 'your-chatbot-id',
        'messages': [{'role': 'user', 'content': 'Hello'}],
    },
)

cURL

export AGENTKIT_API_KEY="your-api-key"

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H "Authorization: Bearer $AGENTKIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"chatbotId": "uuid", "messages": [{"role": "user", "content": "Hello"}]}'

Prossimi passi