redeemable-app-tokens.md

Redeemable app tokens

Justification

In order to permit authors/owners of pay-for Flatpaks to issue access to people, perhaps for testing, or for other development purposes; or even because they themselves need to install their own flatpak via Flathub for some reason, we need to be able to issue application tokens, keys, whatever we want to call them.

Model

Flathub will permit application owners, who have configured an application to require payment, to create one-time redeemable tokens for their applications. These tokens will have names, be redeemable only once, and will record when they are redeemed. Un-redeemed tokens may be cancelled.

Users who hold such a token can redeem it against the application to be granted "ownership" which permits them to acquire a flat-manager token to download the application.

Backend

All behaviour for tokens shall be under /vending/{appid}/tokens.

GET /vending/{appid}/tokens

Retrieve a list of tokens issued for this application. Tokens are always listed in order of creation, newest first, and are paginated. This endpoint returns JSON objects of the form:

{
    "total": nnnn,
    "entries": [
        {
            "id": "some opaque id for pagination",
            "state": "unredeemed/redeemed/cancelled",
            "name": "some name given to the token",
            "token": "if unredeemed, the token, else empty",
            "created": "creation date",
            "changed": "change date, ie. redeemption or cancellation date"
        }
    ]
}

The pagination means that only X (TBD) tokens will be returned each time, and to continue fetching, pass since=$id

If there are no tokens, this endpoint returns {"total": 0} If the application has not been set up for vending, or is a donation-only application then it will return a 204 (no content), and if the caller does not control the application then it will return 403 (forbidden)

POST /vending/{appid}/tokens

If the application has not been set up for vending, or the caller does not control the application, this will return a 403 (forbidden).

This endpoint can be used to create new tokens, POST the following data:

[
    "name for the token",
    "name for another token",
    ...
]

The return content will be:

[
    { token content as per GET for the given token }
    ...
]

This endpoint will not allow the creation of more than X (TBD) tokens at once, and there may be limits of Y (TBD) unredeemed tokens per application.

POST /vending/{appid}/tokens/cancel

If the application has not been set up for vending, or the caller does not control the application, this will return a 403 (forbidden).

The endpoint can be used to cancel tokens, POST the following data:

[
    "token string",
    ...
]

For each token string posted, the backend will cancel the token if it has not already been redeemed, and if the token does not exist it will be ignored.

The return content will be:

[{ "token": "token string", "status": "cancelled/invalid" }]

Where the status for each passed in token-to-cancel is either cancelled if the cancellation succeeded, or invalid if the token was not known or had already been redeemed.

POST /vending/{appid}/tokens/redeem/{token}

Any logged in user may redeem a token by POSTing an empty body to this endpoint.

If the token is valid, then the calling user will be granted ownership of the application, and the token will be marked as redeemed.

The return content will be of the form:

{
  "status": "success/failure",
  "reason": "..."
}

The POST will always succeed, but the return content will indicate either success, in which case the token is marked redeemed and the caller now owns the application, or failure, in which case the reason will be one of:

• invalid: The token passed in was not a valid redeemable token for the given application
• failed: The token was valid, but something went wrong when trying to redeem it