Space and Time operates on a decentralized network, so authenticating directly to that network allows developers the greatest amount of control, flexibility, and speed, without the need to trust any centralized intermediary. The trade-off is that you have to manage cryptographic keys locally and prove authentication and authorization for every request.

📘
Access Tokens are the core connection type - all other connection types are simply wrappers or abstractions around the Access Token workflow.

These instructions explain how to connect and authenticate directly to the Space and Time network using our REST APIs.

Easiest Way to Authenticate: CLI

While you can use the below workflow to manually authenticate to the Space and Time network, it is somewhat hard to do given the 30-second security time-out in which you have to sign and return all information required. We recommend going through the CLI workflow, which will provide the steps for creating a new UserID and keypair. The workflow below is best for users that have already registered and are looking to start building an application on SxT.

Most examples in these docs leverage the SxT CLI and assume all secrets are kept in an .env file.

🚧
Always keep your private key somewhere safe. If you lose your private key, you cannot authenticate as that UserID. To be safe, you can add a new keypair to your UserID's keyring and store a second key as backup.

How to Authenticate to the Network with APIs

Prerequisites

To complete this workflow, you will need:

A Space and Time UserID, which is created with one or more ED25519 public keys. The easiest way to do this is by following the CLI workflow.
A mechanism to cryptographically sign the challenge token with the matching ED25519 private key

Authentication Workflow:

The decentralized authentication is built on a traditional challenge / response model, whereby the user or application requests and signs a challenge token with the local private key. The network then attempts to validate the with the public key, an access token is issued. Below is a map of that call / challenge / response workflow, with the local cryptographic signature work in bold:

Local / Client	Decentralized Network
Request a challenge token for a particular UserID
	Generates and returns a random challenge token for that UserID, which expires after 30 seconds
Sign the challenge token with the UserID's private key, and returns the signed challenge to the network
	Authenticates the client's ownership of the UserID's private key by using the UserID's public key to validate the signed challenge, and returns an ACCESS_TOKEN (25 minute session), a REFRESH_TOKEN (30 minute time-out, for streamlined session refresh), and the epoch expiration time for both
Any time before the Refresh Token times out, can request a refreshed Access Token, which again comes with a new Refresh Token
	Any session that has been active for 24 hours is terminated, forcing a full re-authentication

🚧
Access Tokens ARE your session to the network. Never share or lose control of your Access Token, as it would allow others to issue commands to Space and Time network as you.

How to Terminate a Session

You can request the session be terminated at any time by calling the simple logout API, which will immediately log you out of all sessions.