Authentication

See the Authentication API reference for the interactive playground.

Principal types

DynamoSQL recognizes two principal types:

Type	Description	How to authenticate
Portal user	Human user who logged in via the DynamoSQL portal	Passkey or password + TOTP; portal issues a session
API client	Machine-to-machine service account created in the portal	`POST /v1/auth/token` with `clientId` + `clientSecret`

The /v1/query endpoint is intended for API clients. Portal users typically interact through the portal’s SQL editor.

Getting a token

API clients authenticate by posting their credentials to the token endpoint:

curl -X POST https://api.dynamosql.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

import requests

resp = requests.post(
    "https://api.dynamosql.com/v1/auth/token",
    json={
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
    },
)
data = resp.json()["data"]
access_token = data["accessToken"]
refresh_token = data["refreshToken"]

const resp = await fetch("https://api.dynamosql.com/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  }),
});
const { data } = await resp.json();
const { accessToken, refreshToken } = data;

const resp = await fetch("https://api.dynamosql.com/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  }),
});
const { data } = (await resp.json()) as {
  data: { accessToken: string; refreshToken: string; expiresIn: number };
};

The response contains:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJjdHkiOiJKV1QiLCJl...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

accessToken — JWT valid for one hour. Pass as Authorization: Bearer <accessToken>.
refreshToken — use to obtain a new access token without re-sending credentials.
expiresIn — token lifetime in seconds.

Scopes

Scopes control which endpoints an API client can access. They are assigned when the client is created in the portal.

Scope	Required for
`query`	`POST /v1/query` (both `execute` and `plan` modes)
`schemas:read`	`GET /v1/schemas`, `GET /v1/schemas/{name}`
`schemas:write`	`POST /v1/schemas`, `PATCH /v1/schemas/{name}`, `DELETE /v1/schemas/{name}`, `POST /v1/schemas/{name}/refresh-metadata`, `POST /v1/schemas/{name}/validate-role`
`usage:read`	`GET /v1/usage/summary`

New API clients receive query and schemas:read by default.

Passing the bearer token

Include the token in the Authorization header on every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token refresh

When your access token expires, exchange the refresh token for a new access token instead of re-authenticating with credentials:

curl -X POST https://api.dynamosql.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "YOUR_REFRESH_TOKEN"
  }'

resp = requests.post(
    "https://api.dynamosql.com/v1/auth/refresh",
    json={"refreshToken": refresh_token},
)
data = resp.json()["data"]
access_token = data["accessToken"]

const resp = await fetch("https://api.dynamosql.com/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refreshToken }),
});
const { data } = await resp.json();
const { accessToken } = data;

const resp = await fetch("https://api.dynamosql.com/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refreshToken }),
});
const { data } = (await resp.json()) as {
  data: { accessToken: string; expiresIn: number };
};

The refresh response contains a new accessToken and expiresIn. No new refresh token is issued.

Token caching example

import requests
import time

class TokenCache:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._access_token = None
        self._refresh_token = None
        self._expires_at = 0

    def get(self):
        if time.time() < self._expires_at - 30:  # 30s buffer
            return self._access_token

        # Try refresh first if we have a refresh token
        if self._refresh_token:
            try:
                return self._refresh()
            except Exception:
                pass  # Fall through to full auth

        return self._authenticate()

    def _authenticate(self):
        resp = requests.post(
            "https://api.dynamosql.com/v1/auth/token",
            json={
                "clientId": self.client_id,
                "clientSecret": self.client_secret,
            },
        )
        resp.raise_for_status()
        data = resp.json()["data"]
        self._access_token = data["accessToken"]
        self._refresh_token = data.get("refreshToken")
        self._expires_at = time.time() + data["expiresIn"]
        return self._access_token

    def _refresh(self):
        resp = requests.post(
            "https://api.dynamosql.com/v1/auth/refresh",
            json={"refreshToken": self._refresh_token},
        )
        resp.raise_for_status()
        data = resp.json()["data"]
        self._access_token = data["accessToken"]
        self._expires_at = time.time() + data["expiresIn"]
        return self._access_token

Tenant scoping

Every JWT carries a tenantId claim. The server reads this claim and scopes all DynamoDB access to that tenant’s tables. You cannot query another tenant’s data. The tenantId field in the request body is optional. If provided, it must match the tenantId in the JWT — a mismatch returns 403.

Get Started

Guides

MCP Server

API Reference

SQL Reference

Changelog

Principal types

Getting a token

Scopes

Passing the bearer token

Token refresh

Token caching example

Tenant scoping

​Principal types

​Getting a token

​Scopes

​Passing the bearer token

​Token refresh

​Token caching example

​Tenant scoping

Principal types

Getting a token

Scopes

Passing the bearer token

Token refresh

Token caching example

Tenant scoping