This section provides instructions on how to register and authenticate with an ED25519 keypair by using the CLI or by following the API workflow. ED25519 is best used when building applications on top of Space and Time. They're easy to generate and can be tied to a single application, limiting exposure to potential security risks with deployed applications.

📘

If this is your first time using Space and Time, try walking through our Getting started guide.

Authenticating via Space and Time CLI

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

Authenticating via API workflow

Alternatively, you can register and authenticate by following the authentication API workflow.

Regardless of which workflow you choose, keep the following considerations in mind:

Basic considerations

Choosing a unique user identifier

When accessing the platform, you'll need to create a globally unique a user identifier (userId), meaning one that's not used by anyone else in Space and Time. Make sure you note the userId you pick - you'll use it every time you authenticate with Space and Time.

Generating a public/private keypair

Platform authentication (i.e. proving your identity) is based on public key cryptography, meaning you need a pair of public/private keys (publicKey and privateKey). The gist is that you request challenges from the platform and calculate a signature with your privateKey. The platform verifies the validity of the signature with your publicKey. Note that your privateKey should never be shared with any person for any reason, and will always remain on your machine. Your publicKey is stored in the platform and is safe to share.

Calculating a signature

Generating a valid signature proves you have ownership of your identity.

To calculate the signature, you'll need to have access to your privateKey and know the appropriate key algorithm for generating signatures. In general, it should look something like this:

// Sign the challenge with your private key
var signature = privateKey.sign(authCode);

Refreshing a session

If you've successfully authenticated with the platform and are now wondering how your session can last 24 hours if your accessToken and refreshToken both expire after half an hour, don't worry! All you have to do is refresh your session. Make sure you refresh your session before the expiration time of your refresh token has passed (otherwise, you'll have to go through the normal authentication workflow described above). Instructions for refreshing a session are included in both the CLI instructions and the API workflow.

A few important points:

• Authenticated sessions last a maximum of 24 hours, at which point the user must re-authenticate.
• The accessToken expires after 25 minutes.
• The refreshToken expires after 30 minutes.

More information about public/private key authentication

This section contains extra information on how authentication works in Space and Time.

Key association

One primary difference in registration and authentication is related to the association between user identifier (userId) and public key. During registration, the platform has no knowledge about the user or the user's public key. Thus, when requesting tokens, the user must provide both the public key as well as the key scheme (i.e., the algorithm to use).

After successful registration, the platform will store the given public key and key scheme and associate them with the user's identifier. Going forward the user must only provide the public key in the Token Request API, as the scheme can be retrieved from storage. This has the added benefit that the provided public key in the request will be checked against the user's associated public keys, preventing a malicious actor from associating a new public key with an existing user.

Key management

When registering with the platform for the first time, you must pick one of the supported algorithms (described below). However, you're not stuck with a single key pair or algorithm! Every user has a keychain stored in the platform which can contain any number of valid public keys and their associated algorithms.

Adding a new key to your keychain is very straightforward and similar to the authentication workflow. You request a challenge, sign it with your new private key, and submit a request to add the new public key to your keychain with the signature.

Check out our Key Management APIs to see how to interact with your keychain.

Key algorithms

The platform currently supports the following algorithms for signature-based authentication:

• ED25519 - for building applications on Space and Time
• Ethereum wallets - for accessing Space and Time

Specifying the algorithm in the Token Request API can be done via the following properties:

• key - the public key to validate the signature against
• scheme - the algorithm to use when validating the signature

For ED25519 signature verification, provide the following:

• key: your ED25519 public key
• scheme: "ed25519"

For Ethereum wallet signature verification, provide the following:

• key: your wallet address
• scheme: the Ethereum chain id (see EIP-155 for specifics)