These instructions explain how to register and authenticate with Space and Time by using Python to interact with our Security/Auth REST APIs.
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.
If this is your first time using Space and Time, try walking through our Getting started guide.
- You can find the code for this guide in the repository.
- These scripts were created using Python version 3.11.2, but any version of Python 3 should work. If you're using Pyenv, you can create a virtualenv named:
api-test-3.11.2and it will automatically invoke the correct Python virtual environment.
- Install dependencies:
pip install -r requirements.txt
Step 1: Generate a new 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.
While Space and Time supports multiple different key algorithms, we're going to keep it simple and focus on two:
Please see the key algorithms section for more details.
- secp256k1 (Ethereum Accounts/Wallets)
To create key pairs using both algorithms simply execute the script:
Ethereum based keypair: private key: 0xYOUR_PRIVATE_KEY_HERE public key: 0xYOUR_PUBLIC_KEY_HERE ED25519 based keypair: private key: YOUR_PRIVATE_KEY_HERE= public key: YOUR_PUBLIC_KEY_HERE=
You only need to select one keypair, and we currently recommend using ED25519. You can always add more keys to your account, but for now, we'll just need one pair.
Save your keys to a password manager and close out the terminal window.
Step 2: Register a globally unique user identifier (
To register a new
userId through the API you will need three things:
- Public/private keypair (generated in Step 1)
- SxT API URL
- Your organization code
Next we will add those values to a .env file:
cp sample.env .env
Update the your new
.env file with the appropriate values accordingly.
register-authenticate.py script is meant to demonstrate a few basic workflows.
- It will check if the
- If it does exist, it will authenticate and return your
- If not, it will register the
userId, authenticate, and return your
python register-authenticate.py <user_id>
For if a user doesn't exist:
python register-authenticate.py b0bby INFO:root:Checking id: b0bby with URL: XXX INFO:root:UserID doesn't exist! INFO:root:Lets create your user ID! INFO:root:Authenticaiton to the SxT API has been completed successfully! Access token: eyJ0eXBlIjoiYWNjZXNzIiwia2lkIjoiZTUxNDVkYmQtZGNmYi00ZjI4...
And if the user does:
python register-authenticate.py b0b INFO:root:Checking id: b0b with URL: XXX INFO:root:UserID exists! INFO:root:Time to authenticate! INFO:root:Authenticaiton to the SxT API has been completed successfully! Access token: eyJ0eXBlIjoiYWNjZXNzIiwia2lkIjoiZTUxNDVkYmQtZGNmYi00ZjI4L...
Completing the above steps successfully will create a new authenticated session with the platform, and you will receive access and refresh tokens. A few important points:
- Authenticated sessions last a maximum of 24 hours, at which point the user must re-authenticate.
accessTokenmust be specified in the Authorization header (as a bearer token) for all non-Security APIs. It expires after 25 minutes.
refreshTokenis used for Security API requests only and expires after 30 minutes.
Refresh your session
In addition to the
refreshToken you receive from the Token Request API, you also receive an
refreshTokenExpires. These are the expiration time (in milliseconds) of each token.
Refreshing an authenticated session is super easy. Just submit a request via the Token Refresh API and provide a valid (i.e., not expired)
You will receive a new
refreshToken (as well as expiration times - it's the same response as the Token Request API). Make sure to update to these new token values. You have now successfully refreshed your session!
Ending a session
So, your access and refresh tokens will expire about half an hour after they were generated - what if you want to explicitly end your authenticated session sooner? To log out, simply submit a request via the Logout API and provide a valid (i.e., not expired)
Updated 1 day ago