API#

Taubot exposes a HTTPS API available at https://taubot.qzz.io/api/.

All data unless otherwise specified should be sent using JSON encoding.

Authentication#

DM SoTech Lon to get a master application key and it’s associated application ID.

Types of keys:

Master Key

Grant Key

Master keys are issued to applications, if requested they can be granted certain taubot permissions, but are notable for their ability to create GRANT keys

Grant keys are issued by a user to an application, it allows them to grant a subset of their taubot permissions to an application

The key being used to make a request should be set as the authorization HTTP header.

Oauth-like flow overview#

(name suggestions are greatly appreciated)

This section pretains to the distribution of Grant Keys to applications.

The flow is as follows:

  1. Application initiates proccess py posting a UUID identifier to /api/oauth-references, and sends the user a link containing the UUID in a query string along with their application ID.

  2. User clicks link and sets the grant scopes they wish to grant to the API.

  3. User returns to application and confirms that they’ve completed the grant process.

  4. Application gets /api/retrieve-key/{reference_id} where reference ID is the ID they set in their post request.

Starting the oauth-like flow#

As mentioned above the application should send a post request to /api/oauth-references containing a UUID used to identify this particular flow.

This UUID should be sent in the POST body json encoded with the key ref_id.

Afterwards, a URL should be sent to the user granting the application permissions. The same reference ID should be included in the querystring, labelled ref_id. the application ID should also be sent in the querystring and labelled aid.

Example Python Code using requests

import requests
from uuid import UUID

# for obvious reasons these should be loaded from a config rather than hardcoded
master_key: str = "master key goes here"
application_id: UUID = UUID("application ID goes here")

def get_auth_link(ref_id: UUID) -> str:
    resp = requests.post(
         "https://taubot.qzz.io/api/oauth-references",
         data={"ref_id": str(ref_id)},
         headers={"Authorization": master_key}
    )
    resp.raise_for_status()

    # since uuids are urlsafe this is fine
    return f"https://taubot.qzz.io/api/oauth/grant?ref={str(ref_id)}&aid={str(application_id)}"

Once the user has completed the grant process, they should inform the application somehow so that the application can then retrieve their token.

Retrieving a token#

Now that the user has confirmed with the application the token has been isued and it’s time for the application to retrieve it’s token

This should be done by sending a get request to /api/retrieve-key/{ref_id} where ref_id is the same UUID used to initiate the claim process.

The response will be json data with the new auth key set as the key attribute.

This key will have the same permissions the user set.

Example Python code using requests

import requests
from uuid import UUID

# for obvious reasons these should be loaded from a config rather than hardcoded
master_key: str = "master key goes here"
application_id: UUID = UUID("application ID goes here")

def retrieve_key(ref_id: UUID) -> str:
   # since UUIDs are urlsafe this is fine
   resp = requests.get(
        f"https://taubot.qzz.io/api/retrieve-key/{str(ref_id)}",
        headers = {}
   )
   resp.raise_for_status()

   return resp.json()["key"]

This token should be persisted somewhere, and used to make requests on behalf of the issuer.

API Reference#

Response Types#

Application#

Application Response Structure#

Key

Type

Description

id

String

The application’s UUID encoded as a string

application_name

String

The name of the application

economy_name

String

The name of the currency of the application’s economy

economy_id

String

The application economy’s UUID encoded as a stringy

owner_id

String

The owner’s discord id encoded as a string since some programming languages can mess up ints that big

Account#

Account Response Structure#

Key

Type

Description

account_id

String

The account’s UUID encoded as a string

owner_id

String

The owner’s discord id encoded as a string since some programming languages can mess up ints that big

account_name

String

The name of the account

account_type

String

The type of account, see the Account Type section below for more info

balance

Integer

The balance of the account in cents - i.e. 100 would be 1t and 101 would be 1.01t

Account Type#

Account Type#

Name

Description

USER

An account type used to represent user accounts on the discord, is used exclusively for personal accounts

GOVERNMENT

An account type used to represent government accounts

CORPORATION

An account type used to represent corporate accounts

CHARITY

An account type used by non-profit accounts

Transaction#

Transaction#

Key

Type

Description

actor_id

String

The person who performed the transactions discord user id encoded as a string

timestamp

Integer

The unix timestamp of when the transaction took place

from_account

String

The account UUID of the account the money was transferred from

to_account

String

The account UUID of the account the money was sent to

amount

Integer

The amount in cents that was transferred

Endpoints#

Here’s an overview of all the requests you can currently make to the API.

GET /api/applications/me#

Returns information about the current application.

Status Codes:

  • 200 OK – Returns an Application object

GET /api/users/(int: user_id)#

Returns the personal account of user_id if it could be found.

Status Codes:

  • 200 OK – Returns an Account object

  • 404 Not Found – A personal account registered to that user could not be found.

GET /api/accounts/by-name/(str: account_name)#

Returns the account of name account_name if it could be found

Status Codes:

  • 200 OK – Returns an Account object

  • 404 Not Found – An account by that name could not be found

GET /api/accounts/(UUID: account_id)#

Returns the account of uuid account_id if it could be found

Status Codes:

  • 200 OK – Retruns an Account object

  • 404 Not Found – An account by that name could not be found

GET /api/accounts/(UUID: account_id)/transactions#

Returns a list of the Transactions to and from that account

Query Parameters:

  • limit – optional limit paramater, specifies the maximum number of transactions to return

Status Codes:

  • 200 OK – Returns a JSON list of Transaction objects

  • 404 Not Found – The account specified could not be found

  • 401 Unauthorized – You do not have the necessary permissions (VIEW_BALANCE) to view the transaction log

POST /api/transactions/#

Creates a new transaction

JSON Parameters:

  • from_account (string) – The account UUID to transfer money from

  • to_account (string) – The account UUID to transfer money to

  • amount (int) – The amount in cents to transfer

Status Codes:

  • 200 OK – Transaction was created sucessfully

  • 404 Not Found – One of the accounts could not be found

  • 401 Unauthorized – Your key doesn’t grant you sufficient permissions to make this transaction