These instructions explain how to register and authenticate with Space and Time using Python to interact with our Security/Auth REST APIs.

📘

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

Prerequisites

• 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.2 and 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 one, Ed25519.

📘

Please see the key algorithms section for more details.

To create an Ed25519 key pair, run the following script: python generate-Ed25519-keys.py

Output:

Private Key (Base64): .....ufxZz6tyYj5stuwLcEd0=
Public Key (Base64): ......R/AeJpt2F54JsNdjaJujg=

Save your keys to a password manager and close out the terminal window.

Step 2: Register a globally unique user identifier (userId)

To register a new userId through the API you will need three things:

1. Public/private keypair (generated in Step 1)
2. SxT API URL
3. 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.

The register-authenticate.py script is meant to demonstrate a few basic workflows.

1. It will check if the userId supplied exists
2. If it does exist, it will authenticate and return your accessToken
3. If not, it will register the userId, authenticate, and return your accessToken

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...

Notes

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.
• The accessToken must be specified in the Authorization header (as a bearer token) for all non-Security APIs. It expires after 25 minutes.
• The refreshToken is used for Security API requests only and expires after 30 minutes.

Refresh your session

In addition to the accessToken and refreshToken you receive from the Token Request API, you also receive an accessTokenExpires and 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) refreshToken.

You will receive a new accessToken and 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) refreshToken.