# Gluo Portal API — Integration reference

> **Status:** Production · OpenAPI 2.3.1 · Last verified 2026-06-21
> **Human-readable page:** https://documents.gluo.eu/api-documentation

## Purpose

The Gluo Portal API is a REST interface for automating organization administration. It mirrors the same contract the Gluo portal uses internally, exposed at a stable public base URL for integrators, scripts, and identity providers.

Authenticate with a long-lived Gluo organization API key (ak_live_…). Keys are minted in the portal by the Motorical account owner under Admin → Organization API keys. Each key is scoped to a single Gluo organization and carries fine-grained read/write permissions.

> This API governs Gluo org data (users, mailboxes, domains, etc.). It is separate from the Motorical SMTP send API (POST /v1/send) used for outbound mail delivery.

## Base URL

```
https://motorical.com/api/gluo
```

## Authentication

Send your API key on every request using the Authorization header:

```http
Authorization: ApiKey ak_live_<prefix>_<secret>
```

Keys are org-scoped. The backend resolves your Gluo organization from the key — do not send X-Active-Org-Id (that header is for browser sessions on gluo.eu only).

## Idempotency (writes)

Every POST, PUT, PATCH, and DELETE must include a UUID v4 idempotency key:

```http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

Same key + same request body replays the cached response. 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`

## Getting started

1. Sign in to the Gluo portal as the Motorical account owner for your organization.
1. Open Admin → Organization API keys and create a key with the scopes you need.
1. Copy the ak_live secret immediately — it is not shown again.
1. Call GET /org to confirm connectivity, then integrate against the endpoints below.
1. Run write operations with a fresh Idempotency-Key per logical action.

## Endpoints

### Users

Create, update, archive, restore, and manage portal access and mailbox attachment for organization members.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/users` | List organization users | no | no |
| POST | `/users` | Create user | yes | required |
| GET | `/users/{userId}` | Get user | no | no |
| PATCH | `/users/{userId}` | Update user profile/role | yes | required |
| DELETE | `/users/{userId}` | Delete user (GDPR erasure options) | yes | required |
| POST | `/users/{userId}/archive` | Archive user | yes | required |
| POST | `/users/{userId}/restore` | Restore archived user | yes | required |
| GET | `/users/{userId}/mailbox` | Get attached mailbox | no | no |
| POST | `/users/{userId}/portal-password/rotate` | Rotate portal password | yes | required |

### Groups

Distribution groups, membership, bulk member changes, and address-book visibility.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/groups` | List groups | no | no |
| POST | `/groups` | Create group | yes | required |
| GET | `/groups/{groupId}` | Get group | no | no |
| PUT | `/groups/{groupId}` | Update group | yes | required |
| DELETE | `/groups/{groupId}` | Delete group | yes | required |
| POST | `/groups/members/bulk` | Bulk add/remove members | yes | required |
| GET | `/groups/{groupId}/members` | List group members | no | no |
| PUT | `/groups/{groupId}/members` | Replace member set | yes | required |
| PATCH | `/groups/{groupId}/address-book-visibility` | Update directory visibility | yes | required |

### Resources

Meeting rooms and equipment: CRUD, aliases, tags, and calendar visibility.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/resources` | List resources (rooms/equipment) | no | no |
| POST | `/resources` | Create resource | yes | required |
| GET | `/resources/{resourceId}` | Get resource | no | no |
| PATCH | `/resources/{resourceId}` | Update resource | yes | required |
| DELETE | `/resources/{resourceId}` | Delete resource | yes | required |
| PATCH | `/resources/{resourceId}/address-book-visibility` | Update directory visibility | yes | required |
| GET | `/resources/{resourceId}/aliases` | List resource aliases | no | no |
| POST | `/resources/{resourceId}/aliases` | Add alias | yes | required |
| DELETE | `/resources/{resourceId}/aliases/{aliasId}` | Remove alias | yes | required |
| GET | `/resources/{resourceId}/tags` | List tags | no | no |
| PUT | `/resources/{resourceId}/tags` | Replace tags | yes | required |
| DELETE | `/resources/{resourceId}/tags/{tag}` | Remove tag | yes | required |

### Mailboxes

Credentials, aliases, primary email, encrypted IMAP settings, and certificate operations.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/mailboxes` | List org mailboxes | no | no |
| GET | `/mailboxes/{mailboxId}` | Get mailbox | no | no |
| PATCH | `/mailboxes/{mailboxId}` | Update mailbox metadata | yes | required |
| PATCH | `/mailboxes/{mailboxId}/mailbox-type` | Change mailbox type | yes | required |
| GET | `/mailboxes/{mailboxId}/credentials` | List IMAP/SMTP credentials | no | no |
| POST | `/mailboxes/{mailboxId}/credentials` | Create credential | yes | required |
| POST | `/mailboxes/{mailboxId}/credentials/primary/rotate` | Rotate primary credential password | yes | required |
| DELETE | `/mailboxes/{mailboxId}/credentials/{credentialId}` | Revoke credential | yes | required |
| GET | `/mailboxes/{mailboxId}/aliases` | List mailbox aliases | no | no |
| POST | `/mailboxes/{mailboxId}/aliases` | Add alias | yes | required |
| DELETE | `/mailboxes/{mailboxId}/aliases/{aliasId}` | Remove alias | yes | required |
| PATCH | `/mailboxes/{mailboxId}/primary-email` | Set primary send-as address | yes | required |
| GET | `/mailboxes/{mailboxId}/encrypted-imap/header-visibility` | Get encrypted IMAP header policy | no | no |
| PATCH | `/mailboxes/{mailboxId}/encrypted-imap/header-visibility` | Set header visibility | yes | required |
| POST | `/mailboxes/{mailboxId}/encrypted-imap/certificate-reissue` | Reissue S/MIME certificate | yes | required |

### Domains

Verified domains: DNS records, verification, catch-all, transfer, and deletion checks.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/org/domains` | List verified domains | no | no |
| POST | `/org/domains` | Add domain | yes | required |
| GET | `/org/domains/{domainId}/dns-records` | DNS records for verification | no | no |
| GET | `/org/domains/{domainId}/simple-status` | Verification status summary | no | no |
| GET | `/org/domains/{domainId}/delete-check` | Pre-delete impact check | no | no |
| POST | `/org/domains/{domainId}/verify` | Trigger verification | yes | required |
| POST | `/org/domains/{domainId}/transfer` | Transfer domain ownership | yes | required |
| GET | `/org/domains/{domainId}/catchall` | Get catch-all setting | no | no |
| PUT | `/org/domains/{domainId}/catchall` | Set catch-all | yes | required |
| DELETE | `/org/domains/{domainId}` | Remove domain | yes | required |

### Organization

Org profile, membership configuration, directory settings, address books, and encrypted IMAP org policy.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/org` | Organization profile | no | no |
| DELETE | `/org` | Delete organization (offboarding) | yes | required |
| GET | `/org/membership-config` | Membership/role policy | no | no |
| PATCH | `/org/membership-config` | Update membership policy | yes | required |
| GET | `/org/directory` | Directory/GAL settings | no | no |
| PATCH | `/org/directory` | Update directory settings | yes | required |
| GET | `/org/encrypted-imap-config` | Org encrypted IMAP policy | no | no |
| PATCH | `/org/encrypted-imap-config` | Update encrypted IMAP policy | yes | required |
| GET | `/org/address-books` | List org address books | no | no |
| POST | `/org/address-books` | Create address book | yes | required |
| GET | `/org/address-books/{bookId}` | Get address book | no | no |
| PATCH | `/org/address-books/{bookId}` | Update address book | yes | required |
| DELETE | `/org/address-books/{bookId}` | Delete address book | yes | required |

### Audit

Query governance events and export CSV for compliance workflows.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/audit/events` | Query audit events | no | no |
| GET | `/audit/events/export` | Export audit CSV | no | no |
| GET | `/audit/events/export/subject` | Export events for one subject (requires subject query param) | no | no |

### Bulk operations

Asynchronous CSV-style bulk import for users, groups, resources, mailboxes, and domains.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| POST | `/bulk/users` | Bulk user import job | yes | required |
| POST | `/bulk/groups` | Bulk group import job | yes | required |
| POST | `/bulk/resources` | Bulk resource import job | yes | required |
| POST | `/bulk/mailboxes` | Bulk mailbox import job | yes | required |
| POST | `/bulk/domains` | Bulk domain import job | yes | required |
| GET | `/bulk/jobs/{jobId}` | Poll bulk job status | no | no |

### Encrypted IMAP (org)

List S/MIME certificates and download certificate bundles for client provisioning.

| Method | Path | Summary | Write | Idempotency |
| --- | --- | --- | --- | --- |
| GET | `/encrypted-imap/certificates` | List org encrypted IMAP certificates | no | no |
| GET | `/encrypted-imap/certificate-bundle` | Download certificate bundle | no | no |

## Machine-readable companions

- JSON summary: https://documents.gluo.eu/api-documentation.json
- OpenAPI 3.0 YAML: https://documents.gluo.eu/openapi/gluo-portal-v1.yaml
- llms.txt index: https://documents.gluo.eu/llms.txt

## Errors

- 401 — Missing or invalid API key
- 403 — Valid key but insufficient scope or org policy
- 404 — Resource not found in your organization
- 422 — Validation failure or idempotency conflict
- 429 — Rate limit exceeded
- 500 — Unexpected server error — retry with backoff