Endpoint: Utenti, Organizzazione e Quote

Riferimento degli endpoint di amministrazione dell'organizzazione: chiavi API, utenti, ruoli e permessi, impostazioni dell'organizzazione, capacità attive, quote e registro di audit.

Tutte le richieste usano l'URL base https://ai.askme.it/api/v2 e le intestazioni descritte in Autenticazione.

Scope necessari

Lo scope * copre le impostazioni dell'organizzazione e il registro di audit, ma non la gestione di utenti, ruoli e chiavi API: per questi endpoint la chiave deve avere scope espliciti (per esempio admin.api_keys.read, admin.users.create, admin.roles.update). Le funzioni riservate alla piattaforma (creazione e gestione delle organizzazioni, piani, definizione delle quote) non sono disponibili con una chiave API e rispondono 403.

Chiavi API

Endpoint	Metodo	Permesso	Descrizione
`/api-keys`	GET	`admin.api_keys.read`	Elenco delle chiavi dell'organizzazione.
`/api-keys`	POST	`admin.api_keys.create`	Crea una chiave (vedere sotto).
`/api-keys/{api_key_id}`	GET	`admin.api_keys.read`	Dettaglio di una chiave.
`/api-keys/{api_key_id}`	PATCH	`admin.api_keys.update`	Modifica `name`, `scopes`, `rate_limit_rpm`, `rate_limit_rpd`, `expires_at`. Qualunque altro campo è rifiutato con `422`; una chiave revocata risponde `409`.
`/api-keys/{api_key_id}`	DELETE	`admin.api_keys.revoke`	Revoca la chiave (`204`).
`/api-keys/{api_key_id}/rotate`	POST	`admin.api_keys.create`	Revoca la chiave e ne crea una sostitutiva con le stesse impostazioni; il nuovo valore è restituito una sola volta. Una chiave revocata o scaduta risponde `409`.
`/api-keys/scopes`	GET	`admin.api_keys.create` oppure `admin.api_keys.update`	Codici assegnabili come scope e prefissi esclusi da `*`.

`POST /api-keys`

Campo	In	Tipo	Obbligatorio	Predefinito	Descrizione
`name`	body	string (1–255)	Sì	—	Nome della chiave.
`scopes`	body	string[]	No	`["*"]`	Scope della chiave (si veda Permessi e scope). Uno scope che non corrisponde ad alcun permesso assegnabile è rifiutato con `422` e `rejected_scopes`.
`source_app`	body	string (max 50)	No	`internal`	Applicazione a cui attribuire le richieste della chiave che non inviano `X-Source-App`. Per un'integrazione diretta si consiglia `api_direct`.
`rate_limit_rpm`	body	int (≥1)	No	—	Richieste al minuto; se omesso, nessun limite.
`rate_limit_rpd`	body	int (≥1)	No	—	Richieste al giorno; se omesso, nessun limite.
`expires_in_days`	body	int (1–365)	No	—	Validità in giorni; se omesso, la chiave non scade.

Esempio di richiesta

curl -X POST "https://ai.askme.it/api/v2/api-keys" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "integrazione-crm-prod",
    "scopes": ["agents.read", "chat.agents.list", "conversations.read"],
    "source_app": "api_direct",
    "rate_limit_rpm": 60,
    "expires_in_days": 180
  }'

Esempio di risposta (201 Created)

{
  "api_key": {
    "id": 29,
    "tenant_id": "5b0e2f7a-2c41-4d0e-9a6b-1c9e8f3d4a21",
    "name": "integrazione-crm-prod",
    "key_prefix": "amai_Q7d_x2L-",
    "created_by_user_id": null,
    "status": "active",
    "source_app": "api_direct",
    "scopes": ["agents.read", "chat.agents.list", "conversations.read"],
    "role_id": null,
    "rate_limit_rpm": 60,
    "rate_limit_rpd": null,
    "last_used_at": null,
    "expires_at": "2027-03-23T14:22:12.653337Z",
    "created_at": "2026-09-24T14:22:12.653337Z",
    "updated_at": null
  },
  "plain_key": "amai_Q7d_x2L-..."
}

plain_key è il valore completo della chiave e compare solo in questa risposta e in quella della rotazione.

`GET /api-keys/scopes`

{
  "codes": [
    "admin.api_keys.create",
    "admin.api_keys.read",
    "agents.create",
    "agents.read",
    "analysis.create",
    "chat.agents.list",
    "conversations.read_all",
    "knowledge_bases.read",
    "translation.use"
  ],
  "wildcard": "*",
  "wildcard_excluded_code_prefixes": ["admin.users.", "admin.roles.", "admin.api_keys."]
}

L'elenco codes (qui abbreviato) comprende tutti i permessi che si possono assegnare a una chiave. I codici che iniziano con uno dei prefissi di wildcard_excluded_code_prefixes non sono coperti da * e vanno indicati esplicitamente.

Utenti

Permessi admin.users.*, da assegnare esplicitamente alla chiave.

Endpoint	Metodo	Descrizione
`/users`	GET, POST	Elenco e creazione degli utenti dell'organizzazione.
`/users/{user_id}`	GET, PUT, PATCH, DELETE	Dettaglio, modifica, eliminazione di un utente.
`/users/{user_id}/roles`	GET, POST	Ruoli assegnati a un utente e loro assegnazione.
`/users/me`	GET	Profilo del chiamante. Con una chiave API restituisce l'identità della chiave (`id` nella forma `apikey:<id>`) e i suoi scope nel campo `permissions`: è un modo rapido per verificare quale chiave si sta usando.

Nella creazione e nella modifica di un utente il campo facoltativo language indica la lingua della console per la persona, con un codice di lingua come it o en-GB; se manca, l'account mantiene la lingua predefinita.

Ruoli e permessi

Permessi admin.roles.*, da assegnare esplicitamente alla chiave.

Endpoint	Metodo	Descrizione
`/roles`	GET, POST	Elenco e creazione dei ruoli dell'organizzazione.
`/roles/{role_id}`	GET, PUT, DELETE	Dettaglio, modifica, eliminazione di un ruolo.
`/roles/{role_id}/permissions`	GET, PUT	Permessi del ruolo.
`/roles/{role_id}/feature-flags`	GET, PUT	Capacità abilitate per il ruolo.
`/permissions`	GET	Elenco dei permessi disponibili.
`/permissions/categories`	GET	Permessi raggruppati per area.

Organizzazione

Endpoint	Metodo	Permesso	Descrizione
`/tenants/current`	GET	`admin.settings.read`	Dati dell'organizzazione della chiave.
`/tenants/current`	PATCH	`admin.settings.update`	Modifica dei dati dell'organizzazione.

{
  "id": "5b0e2f7a-2c41-4d0e-9a6b-1c9e8f3d4a21",
  "code": "documentazione",
  "name": "Organizzazione di esempio",
  "slug": "documentazione",
  "status": "active",
  "tier": null,
  "metadata": {},
  "plan_name": null,
  "created_at": "2026-09-24T14:14:48.054310Z",
  "updated_at": null,
  "suspended_at": null,
  "suspension_reason": null
}

Modelli per funzione

Il modello che l'organizzazione usa per ogni funzione della piattaforma, come nella sezione Modelli per funzione della console (vedere Modelli e provider).

Endpoint	Metodo	Permesso	Descrizione
`/model-preferences`	GET	`admin.settings.read`	Elenco delle funzioni con il valore in uso, la sua origine (organizzazione, piattaforma o installazione) e l'indicazione delle funzioni modificabili.
`/model-preferences`	PUT	`admin.settings.update`	Modifica di più funzioni in una sola richiesta; risponde con l'elenco aggiornato.

Nel corpo di PUT, changes associa al codice di ogni funzione il nuovo valore, oppure null per togliere la scelta dell'organizzazione e tornare al modello della piattaforma. I codici sono operational, decisions, insights, translation, evaluation_judge, scraping, ocr, pdf_analysis, document_verify, cv_analysis, content_analysis, desk_triple, desk_suggestions, desk_workflow e desk_attributes. Per la lettura dei documenti, options.engine indica il motore (auto, local, mistral o vision) e options.vision_fallback il modello di riserva.

{
  "changes": {
    "translation": { "model": "gpt-4o-mini" },
    "ocr": { "model": "nome-modello-di-visione", "options": { "engine": "vision" } },
    "insights": null
  }
}

Un modello non presente nel catalogo, non attivo, di tipo o capacità diversi da quelli richiesti dalla funzione o di un provider senza una chiave valida viene rifiutato con 422 e un codice che indica il motivo (per esempio MODEL_NOT_FOUND, MODEL_INACTIVE, MODEL_CAPABILITY, PROVIDER_UNUSABLE).

Capacità (feature flag)

Le capacità indicano quali funzionalità sono attive per l'organizzazione (per esempio analysis, translation, mcp_servers). Un endpoint che dipende da una capacità non attiva risponde 403 con code: FEATURE_FLAG_DISABLED.

Endpoint	Metodo	Descrizione
`/feature-flags`	GET	Elenco delle capacità, con `enabled_for_user` e l'origine dell'impostazione (`source`).
`/feature-flags/{code}`	GET	Dettaglio di una capacità.
`/feature-flags/{code}/check`	GET	Verifica se una capacità è attiva: `{ "code": "translation", "enabled": true }`.

Quote

`GET /quotas/usage`

Utilizzo corrente delle quote del piano. Consente a un'integrazione di verificare quanto resta prima di un'operazione onerosa.

{
  "items": [
    {
      "quota_code": "conversations_per_month",
      "quota_name": "Conversazioni mensili",
      "unit": "conversations",
      "period": "monthly",
      "used": 128,
      "limit": 5000,
      "remaining": 4872,
      "usage_percentage": 2.56,
      "period_start": "2026-09-01T00:00:00Z",
      "period_end": "2026-10-01T00:00:00Z"
    }
  ]
}

Tra i codici restituiti: agents, knowledge_bases, documents_per_kb, conversations_per_month, messages_per_conversation, ai_credits_per_month, file_upload_size_mb, storage_gb, api_keys_per_tenant, webhooks_per_tenant, users_per_tenant. period vale none per le quote non legate a un periodo.

Registro di audit

Permesso: monitoring.audit.

Endpoint	Metodo	Descrizione
`/audit/events`	GET	Eventi di audit dell'organizzazione. Filtri `action`, `resource_type`, `actor_id`, `from_date`, `to_date`; paginazione (`limit` massimo 500).
`/audit/events/export`	GET	Esportazione CSV degli eventi, con gli stessi filtri.
`/audit/catalogue`	GET	Tipi di risorsa (`resource_types`, ciascuno con le proprie `actions`) e tipi di attore (`actor_types`) usabili come filtri.

Esempio di evento:

{
  "id": 6,
  "tenant_id": "5b0e2f7a-2c41-4d0e-9a6b-1c9e8f3d4a21",
  "actor_type": "user",
  "actor_id": "261e3622-8af9-480e-a02f-cf2974c4e3c0",
  "action": "api_key.created",
  "resource_type": "api_key",
  "resource_id": "28",
  "details": {
    "name": "integrazione-crm-prod",
    "scopes": ["*"],
    "key_prefix": "amai_KPX_gO-",
    "source_app": "api_direct",
    "rate_limit_rpm": null,
    "rate_limit_rpd": null,
    "expires_at": null
  },
  "ip_address": "192.0.2.10",
  "timestamp": "2026-09-24T14:22:12.653337Z"
}

Chiavi API​

POST /api-keys​

GET /api-keys/scopes​

Utenti​

Ruoli e permessi​

Organizzazione​

Modelli per funzione​

Capacità (feature flag)​

Quote​

GET /quotas/usage​

Registro di audit​

Pagine correlate​