You can connect directly to Space and Time's decentralized network using Web3 authentication, a method designed for developers who want the highest level of security and flexibility. The authentication mechanism is grounded in public key cryptography, specifically using ED25519 signatures. In this method, you are responsible for generating and managing your own public/private keypair, ensuring that sensitive private keys remain secure on your client machine.

The authentication process relies on the use of JWT (JSON Web Tokens), providing a reliable method for managing sessions and maintaining state between client-server interactions. These tokens, alongside the ED25519 signature scheme, form the core of the authentication process, offering a secure, reliable, and straightforward method for developers to authenticate and interact with the decentralized network.

You can connect directly to the Space and Time network using the following interfaces:

Space and Time Studio (using your Web3 wallet)
REST APIs (using an Access Token)
JDBC

If you choose to log into the Space and Time Studio, using your Web3 wallet, it's as simple as a few clicks. To connect through any of the other interfaces above, you'll need to 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

Web3 authentication is based on public key cryptography, meaning you need a pair of public/private keys (publicKey and privateKey). The gist of this process 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).

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 keypair 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)