API Reference

LOOT's JSON-RPC API is self-serve. You authenticate requests using self-signed JWT tokens—no API keys or registration required. Just generate a keypair, sign your JWT, and start using your database.

Authentication

Every request must include a JWT in the Authorization: Bearer <token> header. The JWT must be signed with ES256 and include your public key in the header.

// JWT Header
{
  "alg": "ES256",
  "typ": "JWT",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "..."
  }
}

// JWT Payload
{
  // Required claims
  "sub": "base64url-thumbprint-of-jwk",
  "iss": "https://self-issued.me",
  "compat": "2025-08-01",
  "db": {
    "name": "my-app",
    "tenant": "user-123"
  },

  // Optional claims
  "schema": "CREATE TABLE ...",
  "before": "INSERT INTO _context ...",
  "after": "DELETE FROM _context;",
  "instead": "SELECT * FROM privileged_table;",
  "destroy": true,
  "exp": 1735689600
}

Your account identifier is the JWK thumbprint of your public key (sub claim). Each database is isolated by the combination of account, database name, and tenant.

Methods

exec

Executes SQL statements against your database. If a schema claim is present, LOOT will apply any necessary migrations first.

Database

Name

Tenant

Schema

SQL Query

Results

Initializing...

Request

{
  "jsonrpc": "2.0",
  "method": "exec",
  "params": {
    "sql": "SELECT * FROM todos WHERE completed = 0",
    "parameters": []
  },
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "rows": [
      {"id": 1, "task": "Learn LOOT SQL", "completed": 0}
    ],
    "rowsRead": 1,
    "rowsWritten": 0
  },
  "id": 1
}

JWT Claims

Required Claims

• sub: Base64url-encoded JWK thumbprint (your account identifier)
• iss: Must be "https://self-issued.me" for self-issued tokens
• compat: API compatibility date ("2025-08-01")
• db.name: Database name
• db.tenant: Tenant identifier within the database

Optional Claims

• schema: DDL statements to apply before execution
• before: Privileged SQL to run before the main query (results not returned)
• after: Privileged SQL to run after the main query (results not returned)
• instead: Privileged SQL to run instead of the main query (results returned)
• destroy: Set to true to destroy the database after execution
• exp: Token expiration time (Unix timestamp)