Authentication Methods

Authentication Methods Explained

Tadabase offers two authentication methods for API requests: API Key Authentication and Bearer Token Authentication. This guide explains when and how to use each method.

Method 1: API Key Authentication

What Is It?

API Key Authentication uses three headers (App ID, App Key, and App Secret) to authenticate every request. This is the primary authentication method for the Tadabase REST API.

When to Use

• Server-to-Server Integration: Backend services, automation scripts, integrations
• Full Access: When you need unrestricted access to data tables and operations
• Simple Operations: CRUD operations that don't require user context
• Administrative Tasks: Tasks, automations, imports, exports

How It Works

Include these three headers in every request:

X-Tadabase-App-id: your_app_id
X-Tadabase-App-Key: your_app_key
X-Tadabase-App-Secret: your_app_secret

Example Request

GET https://api.tadabase.io/api/v1/data-tables/lGArg7rmR6/records

Headers:
  X-Tadabase-App-id: 74QY8R4ENB
  X-Tadabase-App-Key: KbQClTItwTVc
  X-Tadabase-App-Secret: wu3AFIDdmNK1dyaorIIPqyZkvG7ssMs4

Advantages

• Simple to implement
• No additional authentication step required
• Works for all API v1.0 endpoints
• Permissions controlled at API key level

Disadvantages

• No user context (doesn't know who the "logged in" user is)
• Cannot use user-based record rules or permissions
• Not suitable for client-side applications (exposes credentials)

Method 2: Bearer Token Authentication

What Is It?

Bearer Token Authentication allows you to authenticate as a specific user. After logging in a user via the API, you receive a token that represents that user's session. This token is then used for subsequent requests.

When to Use

• User-Specific Operations: When you need to act as a specific user
• Permission-Based Access: When record rules or user permissions matter
• Mobile Apps: Native mobile applications with user login
• Custom Front-ends: Custom web or mobile interfaces with user authentication
• User Context Needed: Operations that require knowing which user is making the request

How It Works

Bearer token authentication is a two-step process:

Step 1: Login User and Get Token

POST https://api.tadabase.io/api/v1.1/{appId}/auth/login

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Content-Type: application/json

Body:
{
  "email": "user@example.com",
  "password": "user_password"
}

Step 2: Use Token in Subsequent Requests

GET https://api.tadabase.io/api/v1/data-tables/lGArg7rmR6/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Authorization: Bearer {token_from_login}

Login Response

When you successfully log in a user, you'll receive:

{
  "type": "success",
  "token": "encrypted_bearer_token_here",
  "user_id": "encoded_user_id",
  "expires_at": "2024-01-21 10:30:00",
  "logged_in_since": "2024-01-14 10:30:00"
}

Advantages

• Operates within user context
• Respects user permissions and record rules
• Suitable for building user-facing applications
• Token expires automatically for security
• Can use "logged in user" filters

Disadvantages

• Requires additional login step
• Tokens expire and need renewal
• More complex to implement
• Limited to operations allowed for that specific user

Combining Both Methods

You can (and often should) use both methods together:

GET https://api.tadabase.io/api/v1/data-tables/lGArg7rmR6/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Authorization: Bearer {user_token}

This provides:

• API-level authentication (the three headers)
• User-level context (the bearer token)

User Authentication Endpoints (API v1.1)

Login

Authenticate a user and receive a token:

POST /api/v1.1/{appId}/auth/login

Body:
{
  "email": "user@example.com",
  "password": "password123",
  "remember": false
}

Logout

Invalidate a user's token:

POST /api/v1.1/{appId}/auth/logout

Headers:
  Authorization: Bearer {token}

Check Token Status

Verify if a token is still valid:

POST /api/v1.1/{appId}/auth/status

Headers:
  Authorization: Bearer {token}

Response:

{
  "type": "success",
  "valid": true,
  "expires_at": "2024-01-21 10:30:00",
  "time_remaining": "6 days 23 hours"
}

Auto Login

Login using email only (requires special API key configuration):

POST /api/v1.1/{appId}/auth/auto-login

Body:
{
  "email": "user@example.com"
}

Magic Link

Generate a passwordless login link:

POST /api/v1.1/{appId}/auth/magic-link

Body:
{
  "email": "user@example.com",
  "user_id": "encoded_user_id",
  "redirect_url": "https://example.com/dashboard",
  "redirect_page_id": "page_id"
}

Response:

{
  "type": "success",
  "token": "encrypted_token",
  "magicLinkUrl": "https://yourapp.tadabase.io/magic-link?token=..."
}

Token Management Best Practices

Store Tokens Securely

• Mobile Apps: Use secure storage (Keychain on iOS, Keystore on Android)
• Web Apps: Store in httpOnly cookies or secure session storage
• Never: Store tokens in localStorage or expose them in URLs

Handle Token Expiration

// Pseudo-code
async function makeAuthenticatedRequest(url) {
  let token = getStoredToken();

  // Check if token is expired
  if (isTokenExpired(token)) {
    token = await refreshToken(); // Re-login user
    storeToken(token);
  }

  return fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
}

Implement Token Refresh Logic

When a token expires, you'll receive a 401 Unauthorized response. Automatically re-authenticate the user:

async function apiRequest(url, options) {
  let response = await fetch(url, options);

  if (response.status === 401) {
    // Token expired, re-login
    const newToken = await loginUser(email, password);
    options.headers.Authorization = `Bearer ${newToken}`;
    response = await fetch(url, options);
  }

  return response;
}

Choosing the Right Method

Scenario	Use API Key	Use Bearer Token
Backend integration	✅ Yes	❌ No
Automation scripts	✅ Yes	❌ No
Mobile app with users	⚠️ Partial (for API keys)	✅ Yes (for requests)
Custom web app	⚠️ Server-side only	✅ Yes (client-side)
Need user permissions	❌ No	✅ Yes
Administrative tasks	✅ Yes	❌ No

Next Steps

Now that you understand authentication, let's dive into core data operations:

→ Working with Records (CRUD Operations)

Learn how to create, read, update, and delete records in your data tables.