Accounts

Catena provides an accounts system that is designed for maximum flexibility. The rest of Catena is designed to not depend on Catena's provided Accounts implementation; as a result, you can bring your own Accounts implementation and swap it out for Catena's.

How does Catena define an account?

The fields on an account are shown below. Catena primarily cares about the account_id and display_name, with the auth_role being the tie in to the authentication system when using Catena's provided accounts implementation.

An account may have an arbitrary number of metadata key-value pairs associated with it. These values are typed in order to enable you to write more robust code.

Creating a new Account

The diagram below shows the default out-of-the-box auth flow for Catena using Twitch Authentication. Each step is described in detail below.

Create a new session

In a default configuration, prior to creating an account (or logging into an existing account) the user must first get a provider login session. This can be thought of as an identifier tied to a third party, like Discord or Twitch that uniquely identifies the user.

After the user hits the LoginWithProvider API and completes the flow, they will have a session in the Catena backend. This session can then be used by the account service to create the user's account.

curl -i -X POST \
  http://localhost:5000/api/v1/authentication/login \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": 1,
    "payload": "test01"
  }'

{
  "redirectUri": "string"
}

Creating a new account / fetching an existing account

After the user has created their login session, they can follow the steps below.

When the AccountsService receives a CreateOrGetAccountFromTokenRequest, it will use the provider account ID, provider display name, and provider type stored in the ProviderLoginPayload in the session store created at login to query the accounts database. This checks whether an account has previously been created with the same provider information.

If such an account exists, the handler for CreateOrGetAccountFromToken will return the account in a CreateOrGetAccountFromTokenResponse. Additionally, it will update the user's session to reference this account.

Otherwise, an account with this provider information will be created, with the role of user by default. Its base-64 representation will be added to the session store, and it will be returned in a CreateOrGetAccountFromTokenResponse by the method handler.

curl -i -X POST \
  http://localhost:5000/api/v1/accounts \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "account": {
    "id": "string",
    "displayName": "string",
    "authRole": "string",
    "metadata": { … },
    "platforms": [ … ]
  }
}

Fetching an existing account by ID

The Catena AccountsService supports fetching an existing account by its ID via GetAccountById.

curl -i -X GET \
  'http://localhost:5000/api/v1/accounts/{accountId}'

{
  "account": {
    "id": "string",
    "displayName": "string",
    "authRole": "string",
    "metadata": { … },
    "platforms": [ … ]
  }
}

Updating an Account

The AccountsService also supports updating an account — specifically its display name and associated metadata — via UpdateAccount.

curl -i -X PATCH \
  'http://localhost:5000/api/v1/accounts/{accountId}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "string",
    "account": {
      "id": "string",
      "displayName": "string",
      "authRole": "string",
      "metadata": {
        "property1": {
          "stringPayload": "string",
          "intPayload": 0,
          "jsonPayload": "string"
        },
        "property2": {
          "stringPayload": "string",
          "intPayload": 0,
          "jsonPayload": "string"
        }
      },
      "platforms": [
        "PLATFORM_UNSPECIFIED"
      ]
    },
    "accountMask": "string",
    "metadataDeletionKeys": [
      "string"
    ]
  }'

{
  "account": {
    "id": "string",
    "displayName": "string",
    "authRole": "string",
    "metadata": { … },
    "platforms": [ … ]
  }
}