matrix-spec-proposals/proposals/1961-integrations-auth.md

MSC1961: Integration manager authentication

A set of common APIs needs to be defined for clients to be able to interact with an integration manager. This proposal covers the authentication portion of that API.

Note: this proposal is part of a larger "Integrations API" which has not yet been defined. See MSC1956 for details.

Proposal

All specified APIs (except /register) will take an Authorization header with a Bearer token returned from a call to /register. This token is used to authorize the request and to identify who is making the request. The token may also be specified as the access_token query string parameter, similar to the Client-Server API.

POST /_matrix/integrations/v1/account/register

Exchanges an OpenID object for a token which can be used to authorize future requests to the manager.

Request body is an OpenID object as returned by /_matrix/client/r0/user/:userId/openid/request_token.

Response is:

{
    "token": "OpaqueString"
}

The token should consist of URL-safe base64 characters. Integration managers should be careful to validate the OpenID object by ensuring the /_matrix/federation/v1/openid/userinfo response has a sub which belongs to the matrix_server_name provided in the original OpenID object.

Applications which register for a token are responsible for tracking which integration manager they are for. This can usually be done by tracking the hostname of the integration manager and matching a token with it.

GET /_matrix/integrations/v1/account

Gets information about the token's owner, such as the user ID for which it belongs.

Besides a token, no other information is required for the request.

Response is:

{
    "user_id": "@alice:example.org"
}

The user_id is the user ID which was represented in the OpenID object provided to /register. Integration managers may be interested in also supplying information about the user's credit balance for paid integrations here. Preferably, custom information is stored under a namespaced key like so:

{
    "user_id": "@alice:example.org",
    "org.example.paid.integrations": {
        "credit": 20000
    }
}

POST /_matrix/integrations/v1/account/logout

Logs the token out, rendering it useless for future requests.

Request body is an empty object. Response body is also an empty object if successful.

Security considerations

Clients should be sure to call /logout where possible when the user is logging out or no longer needs access to a given manager. Clients should additionally be cautious about which managers they register for tokens with, as some integration managers may be untrusted.