Space and Time CLI

Instructions for using the CLI to generate biscuits for your tables.

These instructions detail managing authorization for your tables using the Space and Time CLI. Space and Time uses biscuits for decentralized authorization. For more information on biscuits, see the Biscuit authorization page.

Note: you can run the help command at any point to display information about the specified command. Example:

sxtcli authorize help

Output:

Commands:
  help          Display help information about the specified command.
  keygen        Generate (or regenerate) a biscuit key pair.
  biscuit       Generate a biscuit.
  create-table  Generate table creation authorization metadata.

And for biscuit:

sxtcli authorize help biscuit
Usage: <main class> authorize biscuit [--kafka] [--readOnly]
                                      [--privateKey=<_privateKey>]
                                      [--resourceId=<_resourceId>]
Generate a biscuit.
      --kafka      If set, generate a biscuit with kafka infrastructure
                     permissions
      --privateKey=<_privateKey>
                   The private key (NOTE: does not leave your machine)
      --readOnly   only allow read operations
      --resourceId=<_resourceId>
                   The resource identifier (i.e. SCHEMA_NAME.TABLE_NAME)

Step 1: Generate key pair

❗️

Note: this keypair is entirely separate from the keypair you generated for yourself when you authenticated to Space and Time.

Think about it this way: you have your own keypair for authenticating, and your table has its own keypair for authorizing access. Just like with your own keypair, always keep your table's private key private and secure. You'll share the public key to authorize access.

Generating a new key pair to create biscuits for your tables is easy:

sxtcli authorize keygen

Save your private key somewhere safe, like a password manager. You'll also need it for the next step.

Step 2: Generate a Biscuit

To generate a biscuit, you'll need your privateKey from above, and the resourceId you want to provide authorization too. ResourceId is simply the SCHEMA.TABLE.

sxtcli authorize biscuit --privateKey="<your_private_key_here>" --resourceId="<SCHEMA>.<TABLE>"                                                          

The command will return a biscuit!

EvQCCokCCgpjYXBhYmlsaXR5CgpkZGxfY3JlYXRlChVzZV90dXRf...

With that command, there is something important going on behind the scenes. The SxTCLI is also embedding a series of capabilities into the biscuit token. For example, the following capabilities can be decoded from the token:

capability("ddl_create", "SCHEMA.TABLE");
capability("ddl_drop", "SCHEMA.TABLE");
capability("ddl_alter", "SCHEMA.TABLE");
capability("dml_insert", "SCHEMA.TABLE");
capability("dml_update", "SCHEMA.TABLE");
capability("dml_delete", "SCHEMA.TABLE");
capability("dml_merge", "SCHEMA.TABLE");
capability("dql_select", "SCHEMA.TABLE");

Save your biscuit as you will need it later for different interactions with your table(s) on SxT.

Step 3: Generate CREATE TABLE statement

📘

This step simply generates a sample SQL CREATE TABLE statement. It does not create a new resource in the Space and Time data warehouse.

sxtcli authorize create-table --accessType=public_read --privateKey="<biscuitKey>" --resourceId="<resourceId"
  • This command will return a sample DDL statement that you can use to create a table.