Autenticazione

Tutte le richieste all'API di Archyl richiedono l'autenticazione tramite una chiave API. Questa guida spiega come creare e utilizzare le chiavi API.

Creazione di una Chiave API

Accedi al tuo account Archyl
Vai su Profilo > Chiavi API
Clicca su Crea Chiave API
Configura la tua chiave:
- Nome: Un nome descrittivo (es. "Pipeline CI/CD", "Sviluppo Locale")
- Permessi: Sola lettura o Lettura-Scrittura
- Scadenza: Data di scadenza opzionale
Clicca su Crea
Copia e salva la chiave immediatamente - non verrà mostrata nuovamente

Permessi delle Chiavi API

Permesso	Capacità
Lettura	Visualizzare progetti, elementi, documentazione e dati architetturali
Scrittura	Creare, aggiornare ed eliminare progetti, elementi e documentazione

Scegli i permessi minimi necessari per il tuo caso d'uso.

Utilizzo della Chiave API

Includi la tua chiave API nell'header X-API-Key con ogni richiesta:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Esempio: Elenco Progetti

curl -X GET \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

Esempio: Creare un Sistema

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "description": "Handles payment processing",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Autenticazione Server MCP

Quando si utilizza il Server MCP con assistenti AI, l'autenticazione funziona allo stesso modo:

Claude Code / Claude Desktop

Aggiungi la tua chiave API alla configurazione MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Best Practice di Sicurezza

Proteggi le Tue Chiavi

Non fare mai commit delle chiavi API nel controllo versione
Usa variabili d'ambiente nelle pipeline CI/CD
Ruota le chiavi periodicamente
Usa chiavi separate per ambienti diversi

Variabili d'Ambiente

# Salva in .env (aggiungi a .gitignore)
ARCHYL_API_KEY=your-api-key

# Usa negli script
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

Integrazione CI/CD

Salva la tua chiave API come segreto nella tua piattaforma CI/CD:

GitHub Actions:

- name: Update Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Gestione delle Chiavi API

Visualizzazione Chiavi

Vai su Profilo > Chiavi API per vedere tutte le tue chiavi attive:

Nome della chiave e data di creazione
Livello di permesso
Stato di scadenza
Data ultimo utilizzo

Revoca delle Chiavi

Per revocare una chiave compromessa o inutilizzata:

Vai su Profilo > Chiavi API
Trova la chiave da revocare
Clicca su Revoca
Conferma l'azione

Le chiavi revocate vengono invalidate immediatamente.

Scadenza delle Chiavi

Le chiavi possono essere impostate con scadenza:

Mai: La chiave rimane valida fino alla revoca manuale
30 giorni: Ideale per accessi temporanei
90 giorni: Equilibrio tra sicurezza e praticità
Personalizzata: Imposta qualsiasi data di scadenza

Risposte di Errore

Chiave Non Valida o Mancante

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Stato HTTP: 401 Unauthorized

Permessi Insufficienti

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write permissions"
  }
}

Stato HTTP: 403 Forbidden

Chiave Scaduta

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}