The Space and Time Command Line Interface (CLI) allows you to easily register a username and keypair to use when connecting to Space and Time via JDBC or running REST APIs. To get started, follow the instructions for using the CLI.

🚧

Note that during the Controlled Release, the base URL listed in the API specifications will not be active. Controlled Release participants, please refer to your Controlled Release Guide for the active URL.

Part 1: CLI Setup

These instructions will vary slightly depending on your OS and shell. For more information on how shells work, check out this resource.

Step 1: Prerequisites

• Download the latest version of the CLI here.
• Make sure you're running the latest version of the JavaVM.
  • Select your OS / Chip Architecture
  • Download the file named: jdk-19_*

Step 2: Add the CLI to your shell environment

Mac OSX and Linux

Using your editor of choice, edit your .bash profile file:

Add this line:

alias sxtcli='java -jar <PathToJar>/sxtcli-<LATEST_VERSION>.jar'

Windows

For instructions on adding the CLI to your PATH environment variable on Windows, see this resource.

Step 3: Close and open a new terminal window

Step 4: Test CLI execution

To test that your installation was successful, run this command:

sxtcli help    

If installation was successful, the output should look like this:

------------------------------------OUTPUT------------------------------------
                                                                
Usage: <main class> [COMMAND]
Commands:
  help          Display help information about the specified command.
  authenticate  Enables authentication operations.
  authorize     Enables authorization operations.

Part 2: Authentication

Registering and logging into Space and Time.

📘

For the sake of these instructions, we assume that an environment variable named privateKey has been created that contains the user's private key.

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

sxtcli authenticate help

Output:

Commands:
  help      Display help information about the specified command.
  check-id  Check if a userId is in use.
  keychain  Enables keychains management operations.
  keygen    Generate (or regenerate) an ED25519 key pair.
  login     Initiate a new authenticated session.
  logout    End an authenticated session.
  refresh   Refresh an authenticated session.
  register  Register a new user with the platform.

If you've previously generated a privateKey and publicKey or accessToken, skip to Step 2. Otherwise, start here:

Step 1: Register with Space and Time

Generate a new username and keypair for initial setup with Space and Time. You only need to do this step once.

📘

Usernames in Space and Time must be globally unique.

• Check that your username is available. Example:

sxtcli authenticate check-id --url="example.com" --userId="<userId>"

------------------------------------OUTPUT------------------------------------

UserId '<userId>' in use: true

• Generate a new keypair. Example:

sxtcli authenticate keygen

------------------------------------OUTPUT------------------------------------
ED25519 KeyPair (base64)
Private key: <privateKey>
Public key: <publicKey>

📘

Note: you can add multiple keypairs to your userId with the add command.

• Obtain your organization code and run this command:

sxtcli authenticate register --code="<orgCode>" --privateKey="<privateKey" --url="example.com" --userId=<userId>

• The command will return an accessToken and a refreshToken.

Step 2: Log in

You will need to run the login command each time you need access. Your accessToken will expire after 30 minutes, but you can refresh your session using the refreshToken.

sxtcli authenticate login --privateKey="<privateKey>" --publicKey="<publicKey>" --url="example.com" --userId="<userId>"

• The command will return anaccessToken and a refreshToken.

Refresh your session

• To refresh your session, run this command:

sxtcli authenticate refresh --refreshToken="<refreshToken>" --url="<url>"