Organisations

Les organisations sont les entités de premier niveau dans Capgo. Elles vous permettent de regrouper vos apps, les membres de votre équipe et vos ressources sous une même structure. Chaque organisation peut compter plusieurs membres avec des rôles et des permissions différents.

Cas d'usage courants

• Créer une nouvelle organisation pour votre entreprise
• Gérer les paramètres de l’organisation
• Mise à jour des informations de l’organisation
• Récupérer les détails de l’organisation

Points d'accès

GET

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

Récupérer les informations de l'organisation. Si orgId S'il est fourni dans les paramètres, renvoie une seule organisation. Sinon, renvoie toutes les organisations accessibles.

Paramètres de requête

• orgId (facultatif) : l'ID de l'organisation spécifique à récupérer

Type de réponse

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
}

Exemple de requête

# 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

Exemple de réponse

{
  "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/

Créer une nouvelle organisation.

Lors de l’utilisation d’une clé API, celle-ci doit avoir le org.create et d’un binding actif au niveau de l’organisation. org_admin ou org_super_admin Cela est nécessaire car l’organisation cible n’existe pas encore, ce qui empêche de vérifier le RBAC standard au niveau de l’organisation.

En cas de succès de la requête, Capgo affecte automatiquement la même clé API org_super_admin à la nouvelle organisation.

Remarque

org.create n'est pas accordé par défaut aux nouvelles clés API. Activez Autoriser la création d'organisations dans le formulaire de clé API, ou incluez-le "global_permissions": ["org.create"] lors de la création de la clé via API.

Corps de la requête

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

Exemple de requête

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/

Exemple de réponse

{
  "id": "org_456"
}

Erreur d’autorisation

Si la clé API n’a pas org.create, API renvoie 403:

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

PUT

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

Mettre à jour une organisation existante. Nécessite le rôl’administrateur sur l’organisation cible.

Corps de la requête

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

Exemple de requête

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/

Exemple de réponse

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

Supprimer

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

Supprimez une organisation existante. Nécessite la permission de suppression sur l’organisation cible, généralement via le org_super_admin rôle. Cette action est irréversible et supprimera toutes les applications, bundles (versions) et ressources associées.

Le org.create l’autorisation globale ne permet pas de supprimer des organisations.

Paramètres de requête

• orgId: l’ID de l’organisation à supprimer

Exemple de requête

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

Exemple de réponse

{
  "status": "ok"
}

Gestion des erreurs

Toutes les erreurs utilisent le format d'erreur standard décrit dans la Aperçu de API.

Scénarios d'erreur courants et leurs réponses :

// 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": {}
}

Bonnes pratiques

1. Nom: Utilisez des noms clairs et descriptifs pour les organisations
2. Rôles: Attribuez les rôles appropriés aux membres de l'équipe
3. E-mail: Utilisez un e-mail de groupe pour management_email afin d'éviter les problèmes liés aux changements d'e-mail personnel
4. Logo: Hébergez les logos sur un CDN fiable et utilisez des URL HTTPS

Continuer depuis Organizations

Si vous utilisez Organisations pour planifier les opérations du dashboard et de API, connectez-l’avec Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans API Keys, Appareils pour les détails d'implémentation dans Devices, et Les bundles pour les détails d'implémentation dans Bundles.