# 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.