# 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 |
|---|---|---|
| _account discovery_ -- enumerates the user's account_ids | `accounts` | required for kDrive |
| **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 five 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.

The `accounts` scope is non-negotiable: a standalone or free-tier
kDrive lives on a *different* `account_id` than its kSuite counterpart,
and `/1/accounts` is the only PAT-friendly endpoint that enumerates
**all** account_ids in one call. Without it the kDrive listing will
silently come back empty even though the PAT carries the `drive`
scope, because PowerOn would only know about the kSuite `account_id`
(via PIM Calendar / Contacts) and that one returns no drives.

**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 five** of the following, one by one:

     | Search term | Pick this entry |
     |---|---|
     | `accounts` | `accounts - Manage your accounts` |
     | `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` -- PowerOn does not call
     `/1/profile`.
   - **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 three deterministic steps before
persisting anything -- each step probes exactly one scope:

1. `GET https://api.infomaniak.com/1/accounts` (requires scope
   `accounts`) -- enumerates **all** Infomaniak account_ids the PAT
   can reach. Without this scope kDrive cannot find the owning
   account; the submit fails with HTTP 400 and a message that names
   the missing scope.
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.
3. `GET https://api.infomaniak.com/2/drive?account_id=<first>`
   (requires scope `drive`) -- a clean 200 confirms the `drive`
   scope is on the PAT.

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 knows your account

`/2/drive` requires an integer `account_id` query arg. A user can own
kDrives in several Infomaniak accounts -- typically a kSuite account
plus a standalone (or free-tier) kDrive that lives on its **own**
account_id. The kSuite account_id from PIM Calendar / Contacts only
covers the kSuite case, which is why naive PAT integrations show an
empty kDrive even though there are files.

The `KdriveAdapter` therefore calls `GET /1/accounts` (the only
PAT-friendly endpoint that lists every account_id of a token) and
unions the `/2/drive?account_id=<X>` listing across all returned
account_ids. The result is cached on the adapter instance for the
lifetime of the request, so each browse touches `/1/accounts` at most
once.

The submit endpoint runs the same enumeration as a pre-flight check
before persisting the token; if `/1/accounts` rejects the PAT for
missing the `accounts` 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.