{
  "schema_version": "1.0",
  "document_type": "gluo_portal_api_reference",
  "title": "Gluo Portal API",
  "description": "Official Gluo Portal API reference for org automation: authentication, scopes, idempotency, endpoints, and OpenAPI spec.",
  "last_verified": "2026-06-21",
  "openapi_version": "2.3.1",
  "base_url": "https://motorical.com/api/gluo",
  "authentication": {
    "header": "Authorization",
    "format": "ApiKey ak_live_<prefix>_<secret>",
    "org_scoped": true,
    "portal_session_headers_not_used": [
      "X-Active-Org-Id",
      "wm_auth"
    ]
  },
  "idempotency": {
    "required_on": [
      "POST",
      "PUT",
      "PATCH",
      "DELETE"
    ],
    "header": "Idempotency-Key",
    "format": "uuid-v4",
    "replay_rule": "same key + same body returns cached response",
    "conflict_rule": "same key + different body returns HTTP 422"
  },
  "scopes": [
    "gluo.users.read",
    "gluo.users.write",
    "gluo.groups.read",
    "gluo.groups.write",
    "gluo.resources.read",
    "gluo.resources.write",
    "gluo.mailboxes.read",
    "gluo.mailboxes.write",
    "gluo.domains.read",
    "gluo.domains.write",
    "gluo.audit.read",
    "gluo.directory.read",
    "gluo.address_books.read",
    "gluo.address_books.write",
    "gluo.org.read",
    "gluo.org.write",
    "gluo.bulk.write",
    "gluo.encrypted_imap.read",
    "gluo.encrypted_imap.write"
  ],
  "endpoint_groups": [
    {
      "id": "users",
      "routes": [
        {
          "method": "GET",
          "path": "/users",
          "summary": "List organization users",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/users",
          "summary": "Create user",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/users/{userId}",
          "summary": "Get user",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/users/{userId}",
          "summary": "Update user profile/role",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/users/{userId}",
          "summary": "Delete user (GDPR erasure options)",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/users/{userId}/archive",
          "summary": "Archive user",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/users/{userId}/restore",
          "summary": "Restore archived user",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/users/{userId}/mailbox",
          "summary": "Get attached mailbox",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/users/{userId}/portal-password/rotate",
          "summary": "Rotate portal password",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "groups",
      "routes": [
        {
          "method": "GET",
          "path": "/groups",
          "summary": "List groups",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/groups",
          "summary": "Create group",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/groups/{groupId}",
          "summary": "Get group",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PUT",
          "path": "/groups/{groupId}",
          "summary": "Update group",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/groups/{groupId}",
          "summary": "Delete group",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/groups/members/bulk",
          "summary": "Bulk add/remove members",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/groups/{groupId}/members",
          "summary": "List group members",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PUT",
          "path": "/groups/{groupId}/members",
          "summary": "Replace member set",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "PATCH",
          "path": "/groups/{groupId}/address-book-visibility",
          "summary": "Update directory visibility",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "resources",
      "routes": [
        {
          "method": "GET",
          "path": "/resources",
          "summary": "List resources (rooms/equipment)",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/resources",
          "summary": "Create resource",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/resources/{resourceId}",
          "summary": "Get resource",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/resources/{resourceId}",
          "summary": "Update resource",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/resources/{resourceId}",
          "summary": "Delete resource",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "PATCH",
          "path": "/resources/{resourceId}/address-book-visibility",
          "summary": "Update directory visibility",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/resources/{resourceId}/aliases",
          "summary": "List resource aliases",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/resources/{resourceId}/aliases",
          "summary": "Add alias",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/resources/{resourceId}/aliases/{aliasId}",
          "summary": "Remove alias",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/resources/{resourceId}/tags",
          "summary": "List tags",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PUT",
          "path": "/resources/{resourceId}/tags",
          "summary": "Replace tags",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/resources/{resourceId}/tags/{tag}",
          "summary": "Remove tag",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "mailboxes",
      "routes": [
        {
          "method": "GET",
          "path": "/mailboxes",
          "summary": "List org mailboxes",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/mailboxes/{mailboxId}",
          "summary": "Get mailbox",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/mailboxes/{mailboxId}",
          "summary": "Update mailbox metadata",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "PATCH",
          "path": "/mailboxes/{mailboxId}/mailbox-type",
          "summary": "Change mailbox type",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/mailboxes/{mailboxId}/credentials",
          "summary": "List IMAP/SMTP credentials",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/mailboxes/{mailboxId}/credentials",
          "summary": "Create credential",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/mailboxes/{mailboxId}/credentials/primary/rotate",
          "summary": "Rotate primary credential password",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/mailboxes/{mailboxId}/credentials/{credentialId}",
          "summary": "Revoke credential",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/mailboxes/{mailboxId}/aliases",
          "summary": "List mailbox aliases",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/mailboxes/{mailboxId}/aliases",
          "summary": "Add alias",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/mailboxes/{mailboxId}/aliases/{aliasId}",
          "summary": "Remove alias",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "PATCH",
          "path": "/mailboxes/{mailboxId}/primary-email",
          "summary": "Set primary send-as address",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/mailboxes/{mailboxId}/encrypted-imap/header-visibility",
          "summary": "Get encrypted IMAP header policy",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/mailboxes/{mailboxId}/encrypted-imap/header-visibility",
          "summary": "Set header visibility",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/mailboxes/{mailboxId}/encrypted-imap/certificate-reissue",
          "summary": "Reissue S/MIME certificate",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "domains",
      "routes": [
        {
          "method": "GET",
          "path": "/org/domains",
          "summary": "List verified domains",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/org/domains",
          "summary": "Add domain",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/domains/{domainId}/dns-records",
          "summary": "DNS records for verification",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/org/domains/{domainId}/simple-status",
          "summary": "Verification status summary",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/org/domains/{domainId}/delete-check",
          "summary": "Pre-delete impact check",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/org/domains/{domainId}/verify",
          "summary": "Trigger verification",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/org/domains/{domainId}/transfer",
          "summary": "Transfer domain ownership",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/domains/{domainId}/catchall",
          "summary": "Get catch-all setting",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PUT",
          "path": "/org/domains/{domainId}/catchall",
          "summary": "Set catch-all",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/org/domains/{domainId}",
          "summary": "Remove domain",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "org",
      "routes": [
        {
          "method": "GET",
          "path": "/org",
          "summary": "Organization profile",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "DELETE",
          "path": "/org",
          "summary": "Delete organization (offboarding)",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/membership-config",
          "summary": "Membership/role policy",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/org/membership-config",
          "summary": "Update membership policy",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/directory",
          "summary": "Directory/GAL settings",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/org/directory",
          "summary": "Update directory settings",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/encrypted-imap-config",
          "summary": "Org encrypted IMAP policy",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/org/encrypted-imap-config",
          "summary": "Update encrypted IMAP policy",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/address-books",
          "summary": "List org address books",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "POST",
          "path": "/org/address-books",
          "summary": "Create address book",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/org/address-books/{bookId}",
          "summary": "Get address book",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "PATCH",
          "path": "/org/address-books/{bookId}",
          "summary": "Update address book",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "DELETE",
          "path": "/org/address-books/{bookId}",
          "summary": "Delete address book",
          "write": true,
          "idempotency_key_required": true
        }
      ]
    },
    {
      "id": "audit",
      "routes": [
        {
          "method": "GET",
          "path": "/audit/events",
          "summary": "Query audit events",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/audit/events/export",
          "summary": "Export audit CSV",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/audit/events/export/subject",
          "summary": "Export events for one subject (requires subject query param)",
          "write": false,
          "idempotency_key_required": false
        }
      ]
    },
    {
      "id": "bulk",
      "routes": [
        {
          "method": "POST",
          "path": "/bulk/users",
          "summary": "Bulk user import job",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/bulk/groups",
          "summary": "Bulk group import job",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/bulk/resources",
          "summary": "Bulk resource import job",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/bulk/mailboxes",
          "summary": "Bulk mailbox import job",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "POST",
          "path": "/bulk/domains",
          "summary": "Bulk domain import job",
          "write": true,
          "idempotency_key_required": true
        },
        {
          "method": "GET",
          "path": "/bulk/jobs/{jobId}",
          "summary": "Poll bulk job status",
          "write": false,
          "idempotency_key_required": false
        }
      ]
    },
    {
      "id": "encryptedImap",
      "routes": [
        {
          "method": "GET",
          "path": "/encrypted-imap/certificates",
          "summary": "List org encrypted IMAP certificates",
          "write": false,
          "idempotency_key_required": false
        },
        {
          "method": "GET",
          "path": "/encrypted-imap/certificate-bundle",
          "summary": "Download certificate bundle",
          "write": false,
          "idempotency_key_required": false
        }
      ]
    }
  ],
  "machine_readable_urls": {
    "markdown": "https://documents.gluo.eu/api-documentation.md",
    "json": "https://documents.gluo.eu/api-documentation.json",
    "openapi_yaml": "https://documents.gluo.eu/openapi/gluo-portal-v1.yaml",
    "llms_txt": "https://documents.gluo.eu/llms.txt",
    "human_html": "https://documents.gluo.eu/api-documentation"
  },
  "portal_key_management": {
    "ui_location": "https://gluo.eu/portal → Admin → Organization API keys",
    "actor": "Motorical account owner only"
  }
}