Skip to main content

Authentication

Authentication is a crucial component when interacting with the TimeTime API. This section explains how to authenticate your requests using API keys and how to implement user impersonation for enterprise customers.

Basic Authentication with API Keys​

Every request to the TimeTime API must include your API key for authentication. The API uses Bearer token authentication, where your API key is sent in the Authorization header.

Authorization Header Format​

Authorization: Bearer <your-api-key>

Example Request​

GET https://api.timetime.in/v1/me
Authorization: Bearer tt1.ac507ef948a04fakeApiKey5304fa7b4abd936d8e2add1

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

const timeTimeClient = axios.create({
  baseURL: 'https://api.timetime.in/v1',
  headers: {
    'Authorization': `Bearer ${process.env.TIMETIME_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Example: Get current user profile
async function getUserProfile() {
  try {
    const response = await timeTimeClient.get('/me');
    return response.data;
  } catch (error) {
    console.error('Authentication error:', error.message);
    throw error;
  }
}

Python​

import requests

api_key = "tt1.ac507ef948a04fakeApiKey5304fa7b4abd936d8e2add1"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# Example: Get current user profile
response = requests.get(
    "https://api.timetime.in/v1/me",
    headers=headers
)

if response.status_code == 200:
    user_profile = response.json()
    print(f"Authenticated as: {user_profile['name']}")
else:
    print(f"Authentication failed: {response.status_code}")

cURL​

curl -X GET "https://api.timetime.in/v1/me" \
     -H "Authorization: Bearer tt1.ac507ef948a04fakeApiKey5304fa7b4abd936d8e2add1"

Authentication for Enterprise Customers (User Impersonation)​

TimeTime is a multi-tenant platform, allowing enterprise customers with administrative privileges to make API requests on behalf of their users. This feature is particularly useful for building custom integrations or managing user data programmatically.

Note: User impersonation requires that your API key belongs to a user with tenant ADMIN privileges. See Creating Your Own Tenant for more information.

Impersonation Methods​

TimeTime offers two ways to impersonate users:

  1. By TimeTime User ID - When you know the internal TimeTime user identifier
  2. By External User ID - When you're using your own user identifiers integrated with TimeTime

Impersonation by TimeTime User ID​

Use the X-TT-Impersonated-User-Id header with the TimeTime user's UUID:

GET https://api.timetime.in/v1/me
Authorization: Bearer tt1.ac507ef948a04fakeApiKey5304fa7b4abd936d8e2add1
X-TT-Impersonated-User-Id: e003eabc-cd21-496b-afaf-275a2477681c

JavaScript Example​

// Using the previous axios client configuration
async function getUserProfileByImpersonation(timeTimeUserId) {
  try {
    const response = await timeTimeClient.get('/me', {
      headers: {
        'X-TT-Impersonated-User-Id': timeTimeUserId
      }
    });
    return response.data;
  } catch (error) {
    console.error('Impersonation error:', error.message);
    throw error;
  }
}

Impersonation by External User ID​

If your organization uses external user IDs when creating TimeTime users, you can use these IDs directly with the X-TT-Impersonated-External-User-Id header:

GET https://api.timetime.in/v1/me
Authorization: Bearer tt1.ac507ef948a04fakeApiKey5304fa7b4abd936d8e2add1
X-TT-Impersonated-External-User-Id: 123

JavaScript Example​

async function getUserProfileByExternalId(externalUserId) {
  try {
    const response = await timeTimeClient.get('/me', {
      headers: {
        'X-TT-Impersonated-External-User-Id': externalUserId.toString()
      }
    });
    return response.data;
  } catch (error) {
    console.error('External ID impersonation error:', error.message);
    throw error;
  }
}

Best Practices​

  1. Store API keys securely - Never expose your API keys in client-side code or public repositories
  2. Handle authentication errors gracefully - Implement proper error handling for 401 (Unauthorized) and 403 (Forbidden) responses
  3. Apply impersonation selectively - Only use impersonation when necessary and with appropriate authorization checks
  4. Use HTTPS for all requests - Always use encrypted connections when transmitting authentication credentials
  5. Implement token refresh mechanisms - For long-running applications, consider refreshing API keys periodically

Troubleshooting Authentication Issues​

If you encounter authentication problems:

  • 401 Unauthorized - Your API key is invalid or has been revoked
  • 403 Forbidden - Your API key is valid but doesn't have permission for the requested operation
  • Missing or incomplete impersonation headers - Check that you're using the correct header format
  • Rate limit exceeded - You may be making too many requests in a short time period

Next Steps​

Now that you understand how to authenticate with the TimeTime API, proceed to Services to learn how to work with service definitions that can be booked by users.