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 uses two separate auth mechanisms, each for different purposes:
JWT Bearer Token
Short-lived token for account management: creating and revoking API keys.
Authorization: Bearer <token>POST /v1/auth/loginAPI Key
Long-lived key for data operations: CRUD on your profile, skills, experience, education, projects.
X-API-Key: rst_...POST /v1/auth/api-keysJWT 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 Endpoints
curl -X GET "http://localhost:8000/v1/auth/api-keys" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
The JWT is required for POST /v1/auth/api-keys, GET /v1/auth/api-keys, and DELETE /v1/auth/api-keys/{'{key_id}'}.
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 CRUD
curl -X GET "http://localhost:8000/v1/me/profile" \
-H "X-API-Key: rst_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5"
Use X-API-Key for all /v1/me/* endpoints: profile, skills, experience, education, projects, import, and usage.
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 API key for CRUD
resp = httpx.get(f"{BASE}/v1/me/profile",
headers={"X-API-Key": api_key}
)
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 CRUD
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. JWT used for CRUD, or API key used for auth management. |
| 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. |