Organizzazioni

Le organizzazioni sono le entità di primo livello in Capgo. Ti permettono di raggruppare app, membri del team e risorse sotto un'unica gestione. Ogni organizzazione può avere più membri con ruoli e permessi diversi.

Casi d'uso comuni

• Creazione di una nuova organizzazione per la tua azienda
• Gestione delle impostazioni dell'organizzazione
• Aggiornamento informazioni organizzazione
• Recupero dei dettagli dell'organizzazione

Endpoint

GET

https://api.capgo.app/organization/

Recupera le informazioni sull'organizzazione. Se orgId viene fornito nei parametri, restituisce una singola organizzazione. Altrimenti, restituisce tutte le organizzazioni accessibili.

Parametri di query

• orgId (facoltativo): l'ID dell'organizzazione specifica da recuperare

Tipo di risposta

interface Organization {
  id: string
  created_by: string
  created_at: string
  updated_at: string
  logo: string | null
  name: string
  management_email: string
  customer_id: string | null
}

Esempio di richiesta

# Get all organizations
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

# Get specific organization
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/?orgId=org_123

Risposta di esempio

{
  "data": {
    "id": "org_123",
    "name": "My Company",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "logo": "https://example.com/logo.png",
    "management_email": "admin@example.com",
    "customer_id": "cus_123"
  }
}

POST

https://api.capgo.app/organization/

Crea una nuova organizzazione.

Quando usi una chiave API, la chiave deve avere il permesso org.create globale e un binding corrente con ambito org_admin oppure org_super_admin organizzazione. È necessario perché l'organizzazione di destinazione non esiste ancora, quindi il normale RBAC con ambito organizzazione non può essere verificato su di essa.

Quando la richiesta va a buon fine, Capgo assegna automaticamente la stessa chiave API org_super_admin alla nuova organizzazione.

Nota

org.create non viene concessa di default alle nuove chiavi API. Abilita Consenti la creazione di organizzazioni nel modulo della chiave API, oppure includi "global_permissions": ["org.create"] quando crei la chiave tramite API.

Corpo della richiesta

interface OrganizationCreate {
  name: string
  email?: string
  estimatedMau?: number
  website?: string
}

Esempio di richiesta

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization",
    "email": "admin@example.com",
    "website": "https://example.com"
  }' \
  https://api.capgo.app/organization/

Risposta di esempio

{
  "id": "org_456"
}

Errore di autorizzazione

Se la chiave API non dispone di org.create, API restituisce 403:

{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

PUT

https://api.capgo.app/organization/

Aggiorna un'organizzazione esistente. Richiede il ruolo admin sull'organizzazione di destinazione.

Corpo della richiesta

interface OrganizationUpdate {
  orgId: string
  logo?: string
  name?: string
  management_email?: string
}

Esempio di richiesta

curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }' \
  https://api.capgo.app/organization/

Risposta di esempio

{
  "status": "Organization updated",
  "data": {
    "id": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }
}

ELIMINA

https://api.capgo.app/organization/

Elimina un'organizzazione esistente. Richiede il permesso di eliminazione sull'organizzazione di destinazione, solitamente tramite il org_super_admin ruolo. Questa azione è irreversibile e rimuoverà tutte le app, i bundle (versioni) e le risorse associate.

Il org.create il permesso globale non consente di eliminare le organizzazioni.

Parametri di query

• orgId: l'ID dell'organizzazione da eliminare

Esempio di richiesta

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.capgo.app/organization/?orgId=org_123

Risposta di esempio

{
  "status": "ok"
}

Gestione degli errori

Tutti gli errori seguono il formato standard descritto nella Panoramica di API.

Scenari di errore comuni e relative risposte:

// Missing or invalid API key (HTTP 401)
{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

// The API key has no access to the requested organization
{
  "error": "invalid_org_id",
  "message": "You can't access this organization",
  "moreInfo": { "org_id": "046a36ac-e03c-4590-9257-bd6c9dba9ee8" }
}

// The organization requires API keys with an expiration date (HTTP 401)
{
  "error": "org_requires_expiring_key",
  "message": "This organization requires API keys with an expiration date. Please use a different key or update this key with an expiration date.",
  "moreInfo": {}
}

// Creating an organization without the org.create permission (HTTP 403)
{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

// max_apikey_expiration_days out of range on update
{
  "error": "invalid_max_expiration_days",
  "message": "Maximum expiration days must be between 1 and 365",
  "moreInfo": {}
}

Best practice

1. Denominazione: Usa nomi chiari e descrittivi per le organizzazioni
2. Ruoli: Assegna i ruoli corretti ai membri del team
3. Email: Usa un'email di gruppo per management_email per evitare problemi legati a modifiche dell'email personale
4. Logo: Ospita i loghi su un CDN affidabile e usa URL HTTPS

Continua da Organizations

Se stai usando Organizzazioni per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.