Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tedro.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

The Tedro API uses session-based authentication. Every API request requires two credentials:
  1. A session cookie — proves your identity (set automatically on sign-in)
  2. An x-workspace-id header — specifies which workspace you are accessing

​
Step 1: Sign In

Obtain a session cookie by sending your email and password to the sign-in endpoint:
cURL
curl -X POST https://api.tedro.io/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'
Node.js
const response = await fetch('https://api.tedro.io/api/auth/sign-in/email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'you@example.com',
    password: 'your-password',
  }),
});

// The response includes a Set-Cookie header with the better-auth.session_token cookie.
// In Node.js, you need to extract and store it for subsequent requests.
const setCookie = response.headers.get('set-cookie');
const sessionToken = setCookie?.match(/better-auth\.session_token=([^;]+)/)?.[1];
On success, the response sets a better-auth.session_token cookie. The cURL -c cookies.txt flag saves this cookie to a file for use in subsequent requests.

​
Step 2: Find Your Workspace ID

Your workspace ID is a UUID that identifies which workspace your API calls target. You can find it in the Tedro dashboard URL: 
https://app.tedro.io/app/[workspaceId]/overview
                              ^^^^^^^^^^^^
                              This is your workspace ID

​
Organization-Scoped Access

Tedro uses an organization and workspace hierarchy. Your user account belongs to one or more organizations, each containing one or more workspaces.
  • Your session cookie authenticates your user identity at the organization level
  • The x-workspace-id header selects which workspace within your organization to access
  • You must be a member of the workspace (or an org owner) to access its data

​
Roles

Your workspace role determines which API endpoints you can call:
RoleAccess Level
Org OwnerFull access to all workspaces in the organization
AdminFull access within the workspace — publish workflows, manage tools, configure channels
AgentInbox access and view-only for runs — cannot publish, edit tools, or modify settings
ViewerRead-only access to all workspace data
Attempting an action above your role returns a 403 Forbidden response.

​
Step 3: Make Authenticated Requests

Include both the session cookie and x-workspace-id header on every API call:
cURL
curl https://api.tedro.io/api/workflows \
  -b cookies.txt \
  -H "x-workspace-id: your-workspace-uuid"
Node.js
const response = await fetch('https://api.tedro.io/api/workflows', {
  headers: {
    'Cookie': `better-auth.session_token=${sessionToken}`,
    'x-workspace-id': 'your-workspace-uuid',
  },
});

const data = await response.json();
console.log(data.items);

​
Session Lifecycle

PropertyValue
Session duration7 days (absolute timeout)
Sliding renewalSession token refreshes every 24 hours of activity
Cookie namebetter-auth.session_token
Cookie flagshttpOnly, Secure, SameSite=Lax
Sessions expire after 7 days of inactivity. Active sessions are automatically renewed every 24 hours — you do not need to re-authenticate during normal use.

​
Missing or Invalid Credentials

ScenarioStatusResponse
No session cookie401{"error": "Unauthorized"}
Expired session401{"error": "Unauthorized"}
Missing x-workspace-id header401{"error": "Unauthorized"}
Invalid workspace UUID403{"error": "Forbidden"}
User not a member of workspace403{"error": "Forbidden"}

​
Brute Force Protection

The sign-in endpoint has built-in brute force protection:
  • 5 failed attempts per email+IP combination triggers a lockout
  • Lockout duration: 15 minutes
  • During lockout, the endpoint returns 429 Too Many Requests
  • The counter resets on successful sign-in

​
Rate Limits on Auth Endpoints

EndpointLimit
POST /api/auth/sign-in/email5 requests per 60 seconds
POST /api/auth/sign-up/email3 requests per 5 minutes
POST /api/auth/forget-password3 requests per hour
POST /api/auth/reset-password3 requests per hour
All other /api/auth/*10 requests per minute
The API playground in these docs may not work with cookie-based authentication due to cross-domain restrictions. Use cURL or your own code to test API calls.