145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
# Infomaniak Personal Access Token Setup
|
|
|
|
## Overview
|
|
|
|
PowerOn integrates Infomaniak as a **data-only** authority for the kSuite
|
|
services in the Unified Data Bar:
|
|
|
|
| Service | API scope | Status in PowerOn |
|
|
|---|---|---|
|
|
| **kDrive** -- browse / download files | `drive` | active |
|
|
| **Calendar** -- agendas + events (.ics download) | `workspace:calendar` | active |
|
|
| **Contacts** -- address books + contacts (.vcf download) | `workspace:contact` | active |
|
|
| **Mail** -- mailboxes, folders, `.eml` download | `workspace:mail` | blocked by Infomaniak (no PAT-friendly endpoint) |
|
|
|
|
You should tick **all four scopes** when creating the token even if only
|
|
kDrive, Calendar and Contacts are wired up today -- this avoids a token
|
|
rotation when Mail goes live.
|
|
|
|
**Status of the Mail adapter (2026-04-28):** Infomaniak currently does
|
|
not expose a PAT-authenticated endpoint for mailboxes/folders/messages.
|
|
Every probed route either returns `404` (`/1/mail`, `/2/mail`) or
|
|
`302`-redirects to the OAuth authorize page
|
|
(`/api/mail`, `/api/pim/mail`, `/api/pim/mailbox`, `/api/pim/folder`),
|
|
which is the OAuth-Web-Session path -- bearer PATs are rejected. The
|
|
`/api/mail/?account_id=...` route 301-redirects to an internal Cyrus
|
|
server on `http://mail.infomaniak.com:5000` that is not reachable from
|
|
the public internet. The `workspace:mail` scope is stored on the PAT so
|
|
the Mail adapter can be enabled later with no token rotation, as soon
|
|
as Infomaniak opens a public PAT-friendly endpoint.
|
|
|
|
Infomaniak does not expose its data APIs (`/2/drive/...`, `/1/mail/...`) over
|
|
OAuth 2.0. The OAuth endpoint at `login.infomaniak.com/authorize` only issues
|
|
identity tokens (scopes `openid`, `profile`, `email`, `phone`). Bearer tokens
|
|
that work against the data APIs must be issued manually by the user as a
|
|
**Personal Access Token (PAT)** in the Infomaniak Manager.
|
|
|
|
This is the same model used by GitHub Personal Access Tokens, Notion
|
|
Integration Tokens, and many other vendors. PowerOn never sees the user's
|
|
Infomaniak password.
|
|
|
|
## Prerequisites
|
|
|
|
- An Infomaniak account that has access to at least one kDrive and one mailbox.
|
|
- The PowerOn frontend reachable in the browser; the backend reachable from
|
|
the frontend.
|
|
|
|
## Step 1: Create the token in the Infomaniak Manager
|
|
|
|
1. Open the API-Tokens page directly:
|
|
<https://manager.infomaniak.com/v3/ng/accounts/token/list>
|
|
2. Click **Token erstellen** (Create token).
|
|
3. Fill in the form:
|
|
- **Token name**: anything memorable, for example `PowerOn` or
|
|
`PowerOn DEV`.
|
|
- **Application**: leave it on `Default application`. The "PowerOn"
|
|
application registration is **not** used for PATs.
|
|
- **Scopes** (search box): add **all four** of the following, one by one:
|
|
|
|
| Search term | Pick this entry |
|
|
|---|---|
|
|
| `drive` | `drive - Drive products` |
|
|
| `workspace:mail` | `workspace:mail - Manage your emails` |
|
|
| `workspace:calendar` | `workspace:calendar - Manage your calendars` |
|
|
| `workspace:contact` | `workspace:contact - Manage your contacts` |
|
|
|
|
Do **not** tick `All` -- it grants every Infomaniak API (Hosting,
|
|
Billing, AI, ...). Do **not** add `user_info` or `accounts` --
|
|
PowerOn does not need the Manager-level scopes.
|
|
- **Validity**: any value works. PowerOn does not auto-refresh PATs.
|
|
4. Click **Erstellen** (Create) and **copy the token immediately**. Infomaniak
|
|
shows the token value only once.
|
|
|
|
## Step 2: Paste the token into PowerOn
|
|
|
|
1. Sign in to PowerOn and open **Basisdaten -> Verbindungen**.
|
|
2. Click **Infomaniak**. PowerOn creates a pending connection and opens a
|
|
modal that asks for the Personal Access Token.
|
|
3. Paste the token from Step 1 and click **Verbinden**.
|
|
|
|
PowerOn validates the token in two deterministic steps before
|
|
persisting anything:
|
|
|
|
1. `GET https://api.infomaniak.com/2/drive/init?with=drives`
|
|
(requires scope `drive`) -- enumerates every kDrive the PAT can
|
|
reach, including drives where the user only has `role: 'user'`.
|
|
The "official" listing endpoint (`/2/drive?account_id=...`) is
|
|
filtered to drives where the caller is **Drive-Manager admin** and
|
|
would silently return an empty array for a regular kSuite member,
|
|
so we deliberately avoid it.
|
|
2. `GET https://calendar.infomaniak.com/api/pim/calendar` (requires
|
|
scope `workspace:calendar`; `workspace:contact` works as the
|
|
equivalent fallback) -- yields the user's display name and kSuite
|
|
account_id for the connection label in the UI.
|
|
|
|
On success the connection turns active and the token is stored
|
|
encrypted in the backend; on failure the modal shows which scope is
|
|
missing. The mail scope is stored as part of `grantedScopes` without
|
|
a probe -- it is only consumed once the Mail adapter lands.
|
|
|
|
## Step 3: Verify in the Unified Data Bar
|
|
|
|
Open the **Sources** tab in the Unified Data Bar. The connection appears with
|
|
the Infomaniak label and exposes (today) three child nodes:
|
|
|
|
- **kDrive** -- expand to see drives, then folders and files.
|
|
- **Calendar** -- expand to see calendars, then events; downloads as `.ics`.
|
|
- **Contacts** -- expand to see address books, then contacts; downloads as `.vcf`.
|
|
|
|
Mail will appear as an additional child node once a PAT-friendly endpoint
|
|
is identified; no token rotation needed because the scope is already on
|
|
the PAT.
|
|
|
|
## Rotating or revoking the token
|
|
|
|
- To rotate, repeat Step 1 with a new token, then in PowerOn delete the
|
|
existing Infomaniak connection and create a new one with the fresh token.
|
|
- To revoke, delete the token in the Infomaniak Manager. The PowerOn
|
|
connection will start to fail at the next call; delete it from the
|
|
Verbindungen page to remove the stored bearer.
|
|
|
|
## How the kDrive adapter discovers your drives
|
|
|
|
The official `/2/drive?account_id=<id>` listing is **filtered to
|
|
Drive-Manager admins** -- a regular kSuite member with `role: 'user'`
|
|
sees an empty array even though they can read every file in the
|
|
drive. PowerOn therefore uses `/2/drive/init?with=drives`, which
|
|
returns every drive the PAT can reach regardless of admin role and
|
|
includes the drive's `id`, `name`, `account_id` and the caller's
|
|
`role` in one payload.
|
|
|
|
The `KdriveAdapter` calls this endpoint once per request and caches
|
|
the resulting drive list on the adapter instance. The submit endpoint
|
|
runs the same call as a pre-flight scope check before persisting the
|
|
token; if the PAT does not carry the `drive` scope, the submit fails
|
|
with a clear 400 instead of producing a half-broken connection.
|
|
|
|
## Security notes
|
|
|
|
- PATs are stored exactly like OAuth access tokens for Google or Microsoft:
|
|
encrypted at rest in the gateway database, only ever sent over TLS to
|
|
`api.infomaniak.com`, and never returned to the frontend after submission.
|
|
- The PowerOn backend does not need any Infomaniak client ID or client
|
|
secret -- there is no `Service_INFOMANIAK_*` configuration.
|
|
- Each user manages their own tokens. There is no global "PowerOn Infomaniak
|
|
app" the operator has to register or maintain.
|