Authentication & Setup Guide

Everything you need to start making authenticated API requests. Two auth methods, step-by-step flows, and code examples.

Two Authentication Methods

RESTume supports two auth mechanisms. Owner routes can use either one, but they serve different jobs: JWT for interactive sessions and API keys for long-lived automation.

JWT Bearer Token

Short-lived token for interactive sessions: sign-in lifecycle, account management, API-key administration, admin operations, and owner requests made by a human operator or the CLI.

Header: Authorization: Bearer <token>

Obtained via: POST /v1/auth/login

API Key

Long-lived key for owner automation: scheduled jobs, CI, and other scripted /v1/me/* calls where you want a dedicated automation credential instead of a stored session.

Header: X-API-Key: rst_...

Created via: POST /v1/auth/api-keys

JWT Token Flow

Register an Account

curl -X POST "http://localhost:8000/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "yourname",
    "email": "you@example.com",
    "password": "secureP@ss123",
    "full_name": "Your Name"
  }'

Returns your user profile with id, username, email, and full_name.

Sign in to get a JWT

curl -X POST "http://localhost:8000/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "yourname",
    "password": "secureP@ss123"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Copy the access_token value. You'll use it in the next step.

Use the JWT for Auth and Interactive Owner Endpoints

curl -X GET "http://localhost:8000/v1/me/account" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JWT is required for admin routes and API-key management endpoints. Owner routes under /v1/me/* also accept JWT, which is the preferred interactive path for the CLI and does not consume API-key quota.

API Key Flow

Create an API Key

curl -X POST "http://localhost:8000/v1/auth/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-key"}'

Response:

{
  "id": "b2c3d4e5-6789-abcd-ef01-23456789abcd",
  "name": "my-app-key",
  "raw_key": "rst_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "prefix": "rst_a1b2",
  "is_active": true
}

The raw_key is shown only once. Copy and store it securely.

Use the API Key for Owner Automation

curl -X GET "http://localhost:8000/v1/me/profile" \
  -H "X-API-Key: rst_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5"

Use X-API-Key when you need a long-lived automation credential for /v1/me/*. Interactive owner calls can use the JWT instead.

Code Examples

Python (httpx)

import httpx

BASE = "https://your-restume-instance.com"

# Login
resp = httpx.post(f"{BASE}/v1/auth/login", json={
    "username": "yourname", "password": "secureP@ss123"
})
jwt = resp.json()["access_token"]

# Create API key
resp = httpx.post(f"{BASE}/v1/auth/api-keys",
    headers={"Authorization": f"Bearer {jwt}"},
    json={"name": "my-key"}
)
api_key = resp.json()["raw_key"]

# Use JWT for an interactive owner call
resp = httpx.get(f"{BASE}/v1/me/profile",
    headers={"Authorization": f"Bearer {jwt}"}
)
print(resp.json())

JavaScript (fetch)

const BASE = "https://your-restume-instance.com";

// Login
const loginRes = await fetch(`${BASE}/v1/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "yourname", password: "secureP@ss123" })
});
const { access_token } = await loginRes.json();

// Create API key
const keyRes = await fetch(`${BASE}/v1/auth/api-keys`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${access_token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "my-key" })
});
const { raw_key } = await keyRes.json();

// Use API key for long-lived automation
const profile = await fetch(`${BASE}/v1/me/profile`, {
  headers: { "X-API-Key": raw_key }
}).then(r => r.json());

Common Errors

Status	Meaning	What to Do
401	Unauthorized	Missing or invalid token/key. Check your `Authorization` or `X-API-Key` header.
403	Forbidden	Valid credentials but insufficient permissions. Common causes: non-admin owner key against admin routes, or free-plan access against Pro-only owner features.
422	Validation Error	Request body doesn't match schema. Check required fields and types. Response body contains details.
429	Rate Limited	Too many requests. Wait and retry. Check `Retry-After` header.
404	Not Found	Resource doesn't exist. Check the username or resource ID in your path.