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.
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.
Alternatively, you can register and authenticate by following the authentication API workflow.
Regardless of which workflow you choose, keep the following considerations in mind:
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.
Platform authentication (i.e. proving your identity) is based on public key cryptography, meaning you need a pair of public/private keys (
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.
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);
If you've successfully authenticated with the platform and are now wondering how your session can last 24 hours if your
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.
accessTokenexpires after 25 minutes.
refreshTokenexpires after 30 minutes.
This section contains extra information on how authentication works in Space and Time.
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.
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.
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
For Ethereum wallet signature verification, provide the following:
key: your wallet address
scheme: the Ethereum chain id (see EIP-155 for specifics)
Updated 2 months ago