Using API Keys

Create and authenticate with a traditional API Key on Space and Time!

Often developers prefer a simple, application centric authentication method such as an API Key. Fortunately, Space and Time makes it very easy to generate and manage API Keys using Space and Time Studio!

Let's Get Started!

To be able to validate your script, we'd ask that you generate a new file called Using_API_Keys.sh that you can commit to your branch of the SXT-Community/SXTAccreditation repo at the end of the activity.



Create a New API Key

Often developers prefer a simple, application centric authentication method such as an API Key. Fortunately, Space and Time makes it very easy to generate and manage API Keys using Space and Time Studio!

To Generate or Manage API Keys:

  1. Navigate to Space and Time Studio, click on "Sign in" in the upper-right most corner, and login.

  2. Click on "My Account" in the upper-right most corner (replaces "Sign in") and click on the "Permission and Keys" tab.

  3. On that tab, you will see an API Key section. If you have no defined API Keys, the UI will display the "Create API Key" view:

  4. To create a new API Key, simply add a note (to remind yourself where/how the key will be used) and click "Add"

🚧

Copy and save your API Key! It will never be shown again! If you forget to copy, you'll have to delete and re-create a new key.

👍

Congrats! You've just created your first API Key!


If you have existing keys, you should see the "API Key" management view instead:

From here, you can see existing keys and delete keys (using the trash-can icon on the right).

What is the difference between API Keys are Access Tokens?

An ACCESS_TOKEN is the cryptographic session generated by the Space and Time decentralized network directly, meaning you're connected to the network. Generating an ACCESS_TOKEN requires authentication using an async public/private keypair login and expire every 25 minutes, making it the most secure authorization method, but also slightly more difficult to use.

An API key is managed by a Space and Time Gateway / Secrets Proxy, meaning it is authenticating to a near-chain auth server instead of the decentralized network itself. You can use an API Key to run queries, however there are some API calls that require an ACCESS_TOKEN. However, API Keys are very familiar to most developers, making them easy and fast to work with.

You can always use your authenticated API Key to request a full network ACCESS_TOKEN, allowing your application access to the entire suite of decentralized network APIs using an API Key.

Can I turn my API Key Authorization into an Access Token?

While you can run queries natively with your API Key authentication, there are some API calls that require an ACCESS_TOKEN to fully authenticate. Fortunately, it's easy to use your API Key to generate an ACCESS_TOKEN, with one simple API call:

Head over to the API reference page: https://docs.spaceandtime.io/reference/apikey-authn

From there, you'll be able to drop in your API Key and get back an access token immediately, by simply clicking the "Try It" button on the right, or you can see examples of how to make the API call in your code for a more programmatic approach.


Run a Query with API Key

Let's run this fairly simple TPS comparative query for January, 2024 - first using the API Key directly, then again using the Decentralized Network.

Select 'SUI' as Name, count(*)/86400.00 as TPS from SUI.TRANSACTIONS
where time_stamp between '2024-01-01' and  '2024-01-31'
  union all 
Select 'POLYGON' as Name, count(*)/86400.00 as TPS from POLYGON.TRANSACTIONS
where time_stamp between '2024-01-01' and  '2024-01-31'
  union all 
Select 'zkSync' as Name, count(*)/86400.00 as TPS from zkSyncEra.TRANSACTIONS
where time_stamp between '2024-01-01' and  '2024-01-31'

Run a query with an API Key, using the proxy SQL API

  1. Navigate to the "Proxy SQL" API Endpoint, and fill in parameter values:
    1. apikey - this is your valid API Key
    2. sqlText - this is the SQL above
    3. All other parameters can be left blank
  2. You can click "Try It!" to run within the API Reference Doc, or click on the Copy Text Icon (lower-left) to copy the CURL request and run in a terminal window.

Use the API Key to get an Access_Token, then run a query

  1. Navigate to the "API Key Login" API Endpoint, and fill in parameter values:
    1. apikey - this is your valid API Key
    2. This will return an ACCESS_TOKEN
  2. Navigate to the "Execute SQL" API endpoint, and fill in parameter values:
    1. Authorization - (upper-right, also called Bearer token) this is your newly created ACCESS_TOKEN
    2. sqlText - this is the SQL above
    3. All other parameters can be left blank
  3. You can click "Try It!" to run within the API Reference Doc, or click on the Copy Text Icon (lower-left) to copy the CURL request and run in a terminal window.

👍

Congrats! You just ran a query using your API Key!

Space and Time provides API calls that allow you to exchange your Secrets Proxy API_Key, UserName/Password, or active Space and Time Studio SessionID for a decentralized ACCESS_TOKEN. This in turn allows you to operate any API on the entire Space and Time network.



Get Credit:

You'll get credit for this activity if you:

How should I commit my branch changes?

When you're complete with the activity, simply commit your changes to your branch of work, then push to the SXT-Community/SXTAccreditation repo. Many IDEs have automated processes to manage this for you, but to do this manually by opening a temrinal / WSL window, and typing:

  • Line 1: Change to your work folder in your SXT-Community/SXTAccreditation directory
  • Line 2: Make sure your branch is active
  • Line 3: Add all changed files to your local stage
  • Line 4: Commit your changes
  • Line 5: Push your commited changes to github!
cd ./your/path/SXTAccreditation/<your_folder>
git checkout <your_branch>
git add .  
git commit -m "added my new working file"
git push

If you get an error on line 5 saying, The current branch stephens_work has no upstream branch, this is because Github doesn't know about your branch yet. Simply run the command the git tool recommends - it will look something like:
git push --set-upstream origin <your_branch>

When you're done for the day, head over to SXT-Community/SXTAccreditation/Pulls page on Github, and (if you're logged in) you'll see a message like:

Click on the button above to create a Pull Request, give us some feedback in the description, and click "Create Pull Request". Done!