Organizzazioni

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

Uso comune

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

Punti di accesso

GET

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

Recupera informazioni sull'organizzazione. Se orgId è fornito nei parametri, restituisce un'organizzazione singola. 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/

Creare una nuova organizzazione.

Quando si utilizza una chiave API, la chiave deve avere la permessione globale e una organizzazione-scopata corrente o org.create o org_admin Se si utilizza una chiave __CAPGO_KEEP_0__, la chiave deve avere la permessione globale e una organizzazione-scopata corrente o org_super_admin legame. Ciò è richiesto perché l'organizzazione di destinazione non esiste ancora, quindi il controllo RBAC normale non può essere eseguito contro di essa.

Quando la richiesta ha successo, Capgo assegna automaticamente la stessa API chiave all'organizzazione nuova. org_super_admin Nota

La gestione delle chiavi __CAPGO_KEEP_0__ non è autorizzata di default per le nuove chiavi. Abilita

org.create is not granted to new API keys by default. Enable nella forma di chiave __CAPGO_KEEP_0__, o includi quando si crea la chiave attraverso il API. "global_permissions": ["org.create"] when creating the key through the API.

Sezione intitolata “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/

Esempio di Risposta

{
  "id": "org_456"
}

Errore di Autorizzazione

Se la chiave API non è presente org.createil API restituisce:

{
  "error": "permission_denied"
}

PUT

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

Aggiorna un'organizzazione esistente. Richiede il ruolo di amministratore 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/

Esempio di risposta

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

CANCELLA

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

Cancella un'organizzazione esistente. Richiede la possibilità di cancellare l'organizzazione di destinazione, tipicamente attraverso il org_super_admin ruolo. Questa azione è irreversibile e rimuoverà tutti gli app associati, bundle (versioni) e risorse.

La org.create permesssione globale non consente di cancellare le organizzazioni.

Parametri di query

• orgId: L'ID dell'organizzazione da cancellare

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

Scenari di errore comuni e le loro risposte:

// Invalid API key
{
  "error": "Invalid API key",
  "status": "KO"
}

// Missing required field
{
  "error": "Name is required",
  "status": "KO"
}

// Insufficient permissions
{
  "error": "Admin role required",
  "status": "KO"
}

Prassi raccomandate

1. Nomina: Utilizza nomi descrittivi chiari per le organizzazioni
2. Ruoli: Assegna ruoli appropriati ai membri del team
3. Indirizzo e-mailcontext
4. : Utilizza un indirizzo e-mail di gruppo per il management_email per evitare problemi con le modifiche all'indirizzo e-mail personaleLogo

: Host i loghi su un CDN affidabile e utilizza URL HTTPS

Se stai utilizzando Organizzazioni per pianificare dashboard e API operazioni, collega il tuo account con API Panoramica per i dettagli di implementazione in API Panoramica Introduzione per i dettagli di implementazione in Introduzione API Chiavi per i dettagli di implementazione in API Chiavi Dispositivi per i dettagli di implementazione in Dispositivi, e Bundle per i dettagli di implementazione in Bundle