Chiavi API e autenticazione

Ogni chiamata REST e ogni sessione MCP si autentica con una chiave API che crei nell’app. Una chiave agisce come te, limitata alle autorizzazioni che le assegni. Esiste un solo tipo di chiave e un solo header, sia per l’API REST sia per il server MCP.

app.stickyprompts.com/settings#api 1 Crea una chiave 2 L'unico header necessario 3 Rinomina, cambia ambito o elimina

Creare una chiave

1. Apri Settings > API keys

   Vai in Settings e seleziona API keys.

2. Genera una chiave

   Seleziona Generate key. Dalle un nome che indichi dove verrà usata (per esempio Northwind CRM sync) e spunta le autorizzazioni di cui ha bisogno: consulta il riferimento delle autorizzazioni.

3. Copia la chiave

   La chiave completa viene mostrata una sola volta, subito dopo la creazione. In seguito non è più recuperabile, né da te né da StickyPrompts. Salvala subito nel tuo secret manager.

Le chiavi può crearle solo un utente che ha effettuato l’accesso all’app. Gli endpoint di gestione delle chiavi non si possono chiamare con una chiave API, quindi una chiave non può mai creare, elencare o modificare altre chiavi.

Formato della chiave

STICKY-API-<64 characters>

• Il prefisso è sempre STICKY-API-, seguito da 64 caratteri casuali. La chiave completa è lunga 75 caratteri.
• La parte casuale usa cifre, consonanti (niente vocali), - e _.
• StickyPrompts conserva solo un hash del segreto, più i suoi primi 16 caratteri per ritrovarlo. Per questo una chiave persa non può essere mostrata di nuovo.

Ciclo di vita

Inviare la chiave

Invia la chiave come bearer token nell’header Authorization di ogni richiesta:

Authorization: Bearer STICKY-API-...

Il prefisso Bearer STICKY-API- distingue tra maiuscole e minuscole e deve essere esatto. Non esistono alternative tramite query string o cookie.

curl https://api.stickyprompts.com/api/v1/workspace \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os
import requests

r = requests.get(
    "https://api.stickyprompts.com/api/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
)
print(r.status_code, r.json())

const res = await fetch("https://api.stickyprompts.com/api/v1/workspace", {
  headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` },
});
console.log(res.status, await res.json());

(GET /workspace richiede l’autorizzazione organization_get.)

Cosa vede una chiave

Una chiave agisce come l’utente che l’ha creata. Vede esattamente ciò che vede quell’utente - il suo workspace, i suoi progetti e ciò che è stato condiviso con lui - e le sue autorizzazioni restringono ulteriormente questo perimetro. Non è possibile limitare una chiave a un singolo workspace o progetto.

Se il tuo account non è più attivo, smettono di funzionare anche le tue chiavi. Se lasci un workspace o perdi l’accesso a un progetto, anche le tue chiavi perdono quell’accesso.

Come viene verificata una richiesta

Ogni richiesta passa per questi controlli, in quest’ordine. Il primo che non va a buon fine determina la risposta.

A parte questo, le richieste provenienti da una regione non servita dal servizio vengono rifiutate con 403 {"error":"access from your region is not supported"}, sia via REST sia via MCP.

L’errore di autorizzazione indica quella che ti manca, quindi di solito basta modificare la chiave e spuntarla:

{"error": "This api key does not have any of the required permissions. You need at least one of: prompts_get"}

Via MCP il passo 4 funziona diversamente: qualsiasi chiave valida e attiva si connette, e gli strumenti per cui la chiave non ha l’autorizzazione vengono semplicemente nascosti. Consulta Panoramica di MCP.

Route che le chiavi non possono mai usare

Alcune parti dell’API sono riservate a una persona che ha effettuato l’accesso all’app. Su queste una chiave API riceve 403, qualunque autorizzazione abbia:

• Route di account, accesso e autenticazione.
• Route di fatturazione e abbonamento.
• Gestione delle chiavi API (creazione, elenco, modifica ed eliminazione delle chiavi).
• Route di amministrazione riservate al personale di StickyPrompts.
• Alcune route registrate senza un’autorizzazione per chiavi API, per esempio la lettura di un singolo prompt GET /prompt/:id e la condivisione degli agenti (GET /agents/:id/shares e le route PATCH /agents/:id/share_with_*). Gli agenti si condividono dall’app.

Tenere al sicuro le chiavi

• Solo lato server. Conserva le chiavi in variabili d’ambiente o in un secret manager. Non includerle mai in un commit, non scriverle nei log e non incollarle in ticket o chat.
• Privilegio minimo. Spunta solo le autorizzazioni che l’integrazione usa davvero. Un bot di reportistica non ha bisogno di integration_email_manage. Parti dai set consigliati.
• Una chiave per integrazione. Dai a ogni chiave il nome del sistema che la usa. Così puoi revocare un’integrazione senza toccare le altre e capire dall’ultimo utilizzo se è ancora attiva.
• Ruota le chiavi. Sostituiscile con la cadenza che preferisci, e subito quando se ne va qualcuno che vi aveva accesso o quando una chiave potrebbe essere stata esposta. Crea prima la nuova chiave, fai il passaggio, poi elimina quella vecchia.
• Ricorda per conto di chi agisce la chiave. Una chiave agisce come te. Per un’integrazione condivisa, valuta di creare la chiave da un account i cui accessi corrispondano a ciò che l’integrazione deve vedere.

Pagine correlate