Authentication

AppAPI introduces a distinct method of authentication for external apps. This authentication relies on a shared secret between Nextcloud and the external app.

Authentication flow

  1. ExApp sends a request to Nextcloud

  2. Nextcloud passes request to AppAPI

  3. AppAPI validates request (see authentication flow in details)

  4. Request is accepted/rejected

sequenceDiagram participant ExApp box Nextcloud participant Nextcloud participant AppAPI end ExApp->>+Nextcloud: Request to API Nextcloud->>+AppAPI: Validate request AppAPI-->>-Nextcloud: Request accepted/rejected Nextcloud-->>-ExApp: Response (200/401)

Authentication headers

Each ExApp request to secured API with AppAPIAuth must contain the following headers:

  1. AA-VERSION - minimal version of the AppAPI

  2. EX-APP-ID- ID of the ExApp

  3. EX-APP-VERSION - version of the ExApp

  4. AUTHORIZATION-APP-API - base64 encoded userid:secret

Authentication flow in details

sequenceDiagram autonumber participant ExApp box Nextcloud participant Nextcloud participant AppAPI end ExApp->>+Nextcloud: Request to API Nextcloud->>Nextcloud: Check if AUTHORIZATION-APP-API header exists Nextcloud-->>ExApp: Reject if AUTHORIZATION-APP-API header not exists Nextcloud->>Nextcloud: Check if AppAPI app is enabled Nextcloud-->>ExApp: Reject if AppAPI is not exists or disabled Nextcloud->>+AppAPI: Validate request AppAPI-->>AppAPI: Check if ExApp exists and enabled AppAPI-->>Nextcloud: Reject if ExApp not exists or disabled AppAPI-->>AppAPI: Validate shared secret from AUTHORIZATION-APP-API AppAPI-->>Nextcloud: Reject if secret does not match AppAPI-->>AppAPI: Check if user is not empty and active AppAPI-->>Nextcloud: Set active user AppAPI->>-Nextcloud: Request accepted/rejected Nextcloud->>-ExApp: Response (200/401)

AppAPIAuth

AppAPI provides an AppAPIAuth attribute with middleware to validate requests from ExApps. In your API controllers, you can use it as a PHP attribute.

AppAPI session keys

After successful authentication, AppAPI sets the app_api session key to true.

$this->session->set('app_api', true);

Note

The Nextcloud server verifies this session key and allows CORS protection and Two-Factor authentication to be bypassed for requests coming from ExApps. Also, the rate limit is not applied to requests coming from ExApps.