Chiavi API

Una chiave API (detta anche Virtual Key, VK) è la credenziale che i suoi agenti e le sue applicazioni usano per chiamare Everyware AI API. Le chiavi sono compatibili con OpenAI e funzionano con qualsiasi SDK o strumento che parla l'interfaccia REST OpenAI. Il secret ha il prefisso sk-bf-….

Le chiavi API esistono in quattro tipi di chiavi API, che stabiliscono a cosa è legata la chiave, chi può vederla e chi può gestirla. I tipi che può creare dipendono dal suo ruolo.

Tipi di chiavi API

Tipo	Legata a	Visibile a	Quota	Creata da
Chiave API personale	un utente (senza progetto)	il proprietario (+ Admin)	1 per utente	l'utente stesso
Chiave legata a un utente di progetto (privata)	un utente e un progetto IA	solo quell'utente (+ Admin)	1 per utente per progetto IA	l'utente nel progetto, oppure un Admin per conto di un utente
Chiave condivisa di progetto	il progetto IA	tutti i membri del progetto (+ Admin)	—	un Client Admin
Chiave cliente	il cliente (né utente né progetto)	gli Admin	1 per cliente	un Client Admin

Personale o legata a un utente di progetto

Una chiave API personale è legata al suo account del portale e non è vincolata ad alcun progetto IA: può usarla in tutti i progetti. Una chiave legata a un utente di progetto risiede in un progetto IA specifico e eredita i provider, i modelli, il budget e i limiti di quel progetto. Ogni utente ottiene una chiave personale e una chiave legata a un utente di progetto per ogni progetto IA di cui è membro.

Come viene scelto il tipo

Tutti e quattro i tipi vengono creati da un'unica finestra di dialogo Create Key in Key Management. Il tipo è determinato da due campi di quella finestra:

Campo Project (menu a discesa)	User-bound (casella di controllo)	Tipo di chiave risultante
vuoto	☑ selezionata	Chiave API personale (il suo utente, senza progetto)
un progetto IA selezionato	☑ selezionata	Chiave legata a un utente di progetto (lei + il progetto, privata)
un progetto IA selezionato	☐ deselezionata	Chiave condivisa di progetto (il progetto, tutti i membri)
vuoto	☐ deselezionata	Chiave cliente (il cliente, né utente né progetto)

Le combinazioni disponibili dipendono dal suo ruolo

Un utente normale può creare chiavi solo per il proprio uso: chiave API personale e chiave legata a un utente di progetto. Le combinazioni che producono una chiave condivisa di progetto o una chiave cliente sono disponibili solo ai Client Admin. Gli utenti non amministratori non vedono queste opzioni nella finestra di dialogo.

Prerequisiti

• Chiave API personale: un account Cloud Services Portal valido. Nessun progetto IA richiesto.
• Chiave legata a un utente di progetto: un progetto IA a cui è stato invitato. Vedi Progetti IA: un Admin deve prima creare il progetto e invitarla.
• Chiave condivisa di progetto: il ruolo Client Admin.
• Chiave cliente: il ruolo Client Admin.

In tutti i casi serve l'autorizzazione ad accedere al menu AI. Non esiste un "utente IA" separato: si usa il proprio normale account Cloud Services Portal.

Creare una chiave API

1. Vada su AI → Key Management.
2. Clicchi su Create Key.

Nella finestra di dialogo, imposti il campo Project e la casella User-bound per scegliere il tipo di chiave: veda Come viene scelto il tipo per le combinazioni. Ogni chiave ha inoltre un proprio Name e una propria Description, così può distinguerle in seguito (ad esempio per separare un agente di produzione da uno script di test).

• Chiave API personale: lasci Project vuoto, mantenga User-bound selezionata.
• Chiave legata a un utente di progetto: selezioni un progetto IA di cui è membro, mantenga User-bound selezionata. La chiave eredita i provider, i modelli, il budget e i limiti del progetto ed è privata per lei.
• Chiave condivisa di progetto: selezioni un progetto IA, deselezioni User-bound. (Solo Client Admin.) Visibile a tutti i membri del progetto.
• Chiave cliente: lasci Project vuoto, deselezioni User-bound. (Solo Client Admin.) Non legata ad alcun utente o progetto.

Visibilità delle chiavi

Chi può vedere una chiave dipende dal suo tipo:

• Chiave API personale: solo il proprietario. Gli Admin possono elencarla tramite la gestione delle chiavi amministratore (veda Gestire le chiavi (Admin)).
• Chiave legata a un utente di progetto: solo l'utente proprietario. Gli Admin la vedono quando consultano le chiavi del progetto.
• Chiave condivisa di progetto: tutti i membri del progetto IA, più gli Admin.
• Chiave cliente: solo gli Admin.

Ciò significa che una chiave legata a un utente di progetto è privata: gli altri utenti invitati dello stesso progetto non la vedono. Per condividere un'unica chiave tra tutti i membri di un progetto, un Client Admin crea una chiave condivisa di progetto.

Condividere una chiave tra più agenti o utenti

Se più agenti hanno bisogno della stessa chiave, preferisca una chiave condivisa di progetto (creata da un Client Admin) invece di distribuire una chiave personale ai colleghi. Per casi d'uso inter-progetto o di automazione che non devono appartenere a una persona, un account di servizio dedicato sotto Organisation Management mantiene private le chiavi personali e rende la rotazione in caso di cambio di personale un'operazione su un solo utente.

Visualizzare il secret

Quando una chiave viene creata, il suo secret (sk-bf-…) è mascherato. Può mostrare il secret in qualsiasi momento dalla lista delle chiavi, sia in Key Management sia, per le chiavi legate a un progetto, in AI Projects Management sotto il progetto selezionato.

Mostrabile su richiesta

A differenza di un token mostrato una sola volta, il secret non viene visualizzato una volta soltanto. Può mostrarlo di nuovo ogni volta che le serve. Lo tratti come una password: chiunque possa leggerlo può usare la chiave entro il budget e i limiti applicabili al suo tipo.

Warning

Copi il secret in un luogo sicuro: il suo gestore di password, un vault dei segreti o l'ambiente del suo agente. Se sospetta una fuga, revochi o disattivi la chiave immediatamente.

Usare la chiave in un agente

Everyware AI API è compatibile con OpenAI. Punti il suo SDK, agente o CLI OpenAI esistente verso il nostro endpoint e imposti la chiave come token bearer:

• Base URL: https://ai.ewcs.ch/v1

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.ewcs.ch/v1",
    api_key="sk-bf-…your-key…",
)

response = client.chat.completions.create(
    model="ew/glm-5.3-flash",
    messages=[{"role": "user", "content": "Say hello in Swiss German."}],
)
print(response.choices[0].message.content)

• I modelli sono indirizzati nella forma provider/model (ad esempio ew/glm-5.3-flash, anthropic/claude-opus-5-5). I provider e i modelli disponibili per una chiave sono controllati dal suo tipo di chiave API: un progetto IA per le chiavi legate a un utente di progetto e per le chiavi condivise di progetto, la configurazione del cliente per le chiavi cliente.
• Il gateway espone POST /v1/chat/completions, POST /v1/embeddings, POST /v1/rerank e GET /v1/models.

→ Specifica completa dell'interfaccia: API Reference. → Esempi pronti all'uso: AI Use Cases.

Consumo e audit

Il consumo per chiave è mostrato nel pannello AI, nella lista delle chiavi dove la chiave è gestita. È anche il luogo in cui può vedere l'ultimo utilizzo di una chiave.

Dove viene mostrato il consumo

Il consumo delle chiavi è visibile solo nel pannello AI: non compare nella dashboard Usage generale né nel pannello Quota.

Gestire le chiavi (Admin)

I Client Admin possono gestire tutte le chiavi API del proprio cliente (personali, legate a un utente di progetto, condivise di progetto e cliente) da AI → Key Management.

• Elencare e filtrare: elenchi tutte le chiavi del cliente e filtri per utente e/o progetto IA. Ogni chiave indica se è disattivata.
• Rimuovere: elimini definitivamente una chiave. Una chiave rimossa smette di funzionare immediatamente.
• Disattivare: disattivi temporaneamente una chiave senza eliminarla. Una chiave disattivata viene rifiutata dal gateway ma può essere riattivata in seguito.

Le chiavi disattivate vengono eliminate automaticamente dopo 45 giorni

Una chiave che resta disattivata per più di 45 giorni viene eliminata automaticamente. Questa operazione è registrata nel log di audit. Se deve solo sospendere brevemente una chiave, la riattivi entro quel periodo, altrimenti la ricrei dopo l'eliminazione.

Revoca e disattivazione

Può revocare (eliminare) o disattivare una chiave API in qualsiasi momento dalla sua lista delle chiavi in Key Management (o in AI Projects Management per le chiavi legate a un progetto). Gli Admin possono farlo per qualsiasi chiave del cliente tramite Gestire le chiavi (Admin).

La revoca ha effetto immediato

Una chiave revocata o disattivata smette di funzionare immediatamente. Qualsiasi agente che la usa ancora riceverà errori di autenticazione alla richiesta successiva. Esegua prima la rotazione verso una nuova chiave se deve mantenere l'agente in funzione:

1. Crei una nuova chiave dello stesso tipo.
2. Aggiorni la configurazione del suo agente con il nuovo secret.
3. Verifichi che l'agente funzioni.
4. Revochi (o disattivi) la vecchia chiave.

Info

Ruotare regolarmente le chiavi, e ogni volta che un secret potrebbe essere trapelato, è il modo consigliato per mantenere sicuro l'accesso all'IA.