The Authorization API: Platform Saga Part II

This chapter of the “Turso Platform Saga” demonstrates how you authenticate requests, and how to create, validate, list, and revoke API tokens you use to authorize with Turso's Platform API. API tokens belong to you, and grant access to any organization you own or are a member of – we will learn how to create and revoke database tokens in another chapter.

Before you continue, make sure you've read the previous chapters in this series:

• A Hero's API Journey Begins: Platform Saga Part 1

The Turso Platform API secures user requests using Bearer tokens encapsulated within the Authorization header. These tokens, formatted as JSON Web Tokens (JWT), are crucial in the authentication process, providing a secure method for verifying users and granting access to the API that manages your databases and its replicas.

JWTs are preferred for their compact and self-contained way of securely transmitting user information. Each JWT contains encoded JSON objects, including claims about the authentication of the current user and other metadata, which are verifiable with a signature. Bearer tokens, being a type of HTTP authentication, are easily used across various types of HTTP requests, making them ideal for RESTful APIs like ours.

#Sign up to Turso using the CLI

Begin by installing the Turso CLI if you haven't already:

# macOS
brew install tursodatabase/tap/turso

# Linux/Windows WSL
curl -sSfL https://get.tur.so/install.sh | bash

Now signup or login using GitHub:

turso auth signup
# turso auth login

# Windows (WSL)
turso auth signup --headless

You're now ready to go.

#Retrieve temporary API token

The Turso CLI will generate a temporary token once you login that expires in one week.

The temporary nature of the CLI-generated token is designed to balance convenience with security. A shorter expiration reduces the risk associated with the token compromise, as it limits the time an attacker has to exploit a stolen token. This is particularly important for CLI tools, which might be used in less secure environments.

You can retrieve this token by using the following command:

turso auth token

You should get a token that looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDg2OTg5NDEsImlhdCI6MTcwODA5NDE0MSwiaWQiOjEwNTF9.5yGn0R6tAS2092MPWZQtBA5mXm29q8f0WQ6RlTUx744

This token is what is used to authenticate with the Platform API via the Turso CLI. You can use this token to authenticate with the Platform API, however it has a shorter expiration date so it'll no longer be valid in one week.

Understanding the payload of your JWT isn't absolutely necessary to interact with the API, but you can visit jwt.io to inspect the token payload.

#Getting started with the Turso Platform API

The API can be found at the following URL:

https://api.turso.tech

The API is currently v1, so all endpoints begin with /v1 and require the header Authorization in the following format:

Authorization: Bearer [TOKEN]

The requirement for tokens to be included in the Authorization header is in line with the HTTP standard for bearer token usage, ensuring that our API remains compatible with a wide range of HTTP clients and libraries.

Using the token above, we will perform a request to the API to get details about you, the current user:

curl -L 'https://api.turso.tech/v1/current-user' \
  -H 'Authorization: Bearer TEMP_TOKEN'

You should get a response that looks like this:

{
  "user": {
    "avatarUrl": "https://avatars.githubusercontent.com/u/950181?v=4",
    "email": "jamie@notrab.dev",
    "name": "Jamie Barton",
    "plan": "starter",
    "username": "notrab"
  }
}

In the next chapter of The Platform Saga we'll be using the value of username, so make sure you write that down somewhere safe.

#API Tokens

An API token belongs to a user and grants access to any organization you own or are a member of. API Tokens have an id and name that you can use to invalidate anytime.

#Creating permanent API Tokens

Let's begin by creating an API token that doesn't expire, and can be used with any API endpoint:

You'll need to provide a name for the token in the URL, and use the temporary token generated by the CLI:

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/INSERT_TOKEN_NAME \
  -H 'Authorization: Bearer TEMP_TOKEN'

You should see something like this:

{
  "id": "clGFZ4STEe6fljpFzIum8A",
  "name": "my-token",
  "token": "..."
}

The token value is what you'll use with all other API endpoints going forward. This token is never revealed again, so make sure to store this somewhere safe such as an environment file. Never commit it to version control.

#Validating API Tokens

The Turso Platform API provides a useful endpoint to validate API tokens. The API validates the token provided in the Authorization header:

curl -L 'https://api.turso.tech/v1/auth/validate' \
  -H 'Authorization: Bearer TOKEN'

• The exp value is in unix epoch seconds.
• If there is no expiry, the exp value will be -1.
• Invalidate API Tokens return a 401 HTTP status code.

#List API Tokens

You can retrieve a list of API tokens you have created using the API:

curl -L https://api.turso.tech/v1/auth/api-tokens \
  -H 'Authorization: Bearer TOKEN'

You should see something like this:

{
  "tokens": [
    {
      "name": "my-token",
      "id": "clGFZ4STEe6fljpFzIum8A"
    }
  ]
}

The Turso Platform API doesn't store or reveal the token generated previously.

#Revoking API Tokens

The ability to revoke tokens gives you control over your security, allowing you to respond quickly to potential security breaches by invalidating compromised tokens, thus minimizing potential damage.

To revoke a token, pass the name of the API token in the URL and a path parameter, and as a DELETE request:

curl -L -X DELETE 'https://api.turso.tech/v1/auth/api-tokens/my-token' \
  -H 'Authorization: Bearer TOKEN'

You should see a response that includes the name of your token if the request was successful:

{
  "token": "my-token"
}

That's it! We now have the basics covered when working with API Tokens. If you're building a product with Turso as your database infrastructure, you now know the basics of creating, validating and revoking tokens using the Turso Platform API.

See the Turso Platform API Reference for details on each field type.

#Going beyond Auth

In the next chapter we will learn about the Organizations API to invite team members, and much more.

Go to next chapter