Getting Started

This guide will walk you through every step of integrating Tempesly API into your application, from creating your account to making secure API calls in your components.

1

Create Your Account

First, sign up for a Tempesly account to access the dashboard where you'll manage your API keys.

1# Navigate to the registration page
2https://your-app.com/register
3
4# Or sign up via API (programmatically)
5POST https://your-app.com/api/auth/register
6Content-Type: application/json
7
8{
9  "email": "developer@yourcompany.com",
10  "password": "YourSecurePassword123!"
11}

Security Tip: Use a strong, unique password with at least 12 characters including uppercase, lowercase, numbers, and special characters.

2

Generate Your API Key

After logging in, navigate to your dashboard to create an API key. Each key has a name for easy identification.

Via Dashboard (Recommended)

  1. Log in to your account at https://your-app.com/dashboard
  2. Navigate to the "API Keys" section
  3. Click "Create New API Key"
  4. Give your key a descriptive name (e.g., "Production App", "Development", "Mobile App")
  5. Click "Generate Key"
  6. IMPORTANT: Copy your API key immediately - it will only be shown once!

Via API

1# First, log in to get your JWT token
2POST https://your-app.com/api/auth/login
3Content-Type: application/json
4
5{
6  "email": "developer@yourcompany.com",
7  "password": "YourSecurePassword123!"
8}
9
10# Response will include an accessToken
11{
12  "user": { "id": "...", "email": "..." },
13  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
14  "refreshToken": "..."
15}
16
17# Then create your API key
18POST https://your-app.com/api/api-keys
19Authorization: Bearer YOUR_ACCESS_TOKEN
20Content-Type: application/json
21
22{
23  "name": "Production App"
24}
25
26# Response - SAVE THIS! The apiKey is only shown once
27{
28  "id": "api-key-uuid",
29  "name": "Production App",
30  "keyPrefix": "sk_live_a1b2c3d4...",
31  "createdAt": "2026-01-31T12:00:00Z",
32  "apiKey": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
33}

Critical Security Warning:

  • Your API key will ONLY be displayed ONCE during creation
  • Copy it immediately and store it securely (use a password manager or secrets vault)
  • NEVER commit API keys to Git, GitHub, or any version control
  • NEVER share API keys in Slack, email, or public forums
  • If you lose your key, you must delete it and create a new one
  • Treat your API key like a password - it provides full access to your account
3

Set Up Environment Variables (Securely)

For Next.js / React Applications

Create a .env.local file in your project root. This file should NEVER be committed to Git.

1# .env.local (in your project root)
2
3# NEVER use NEXT_PUBLIC_ for API keys that need to stay secret!
4# Server-side only (for API routes, server components, backend operations)
5TEMPESLY_API_KEY=sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
6TEMPESLY_BASE_URL=https://your-app.com
7
8# Optional: If you need client-side access for PUBLIC operations only
9# (e.g., viewing available time slots, creating bookings from a public form)
10# Use a separate, restricted API key with limited permissions
11NEXT_PUBLIC_TEMPESLY_PUBLIC_KEY=sk_live_public_key_here
12NEXT_PUBLIC_TEMPESLY_BASE_URL=https://your-app.com

For Node.js / Express Applications

1# .env (in your project root)
2TEMPESLY_API_KEY=sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
3TEMPESLY_BASE_URL=https://your-app.com
4
5# Load in your app
6# npm install dotenv
7require('dotenv').config()
8
9const apiKey = process.env.TEMPESLY_API_KEY

Secure Your .env Files

Add these lines to your .gitignore file:

1# .gitignore
2.env
3.env.local
4.env*.local
5.env.development.local
6.env.test.local
7.env.production.local

Environment Variable Best Practices:

  • Server-side variables: No prefix (e.g., TEMPESLY_API_KEY) - only accessible in server code
  • Client-side variables: NEXT_PUBLIC_ prefix - exposed to the browser (use only for public data!)
  • Never use NEXT_PUBLIC_ for sensitive keys that grant write access
  • Production: Use your hosting platform's secrets manager (Vercel, Railway, AWS Secrets Manager, etc.)
  • CI/CD: Store secrets in GitHub Secrets, GitLab CI/CD Variables, or your CI platform's vault
4

Install Required Dependencies (Optional)

The Tempesly API uses standard HTTP requests. You can use the native fetch API (built into modern browsers and Node.js 18+) or install additional packages for enhanced functionality.

Option 1: Use Native Fetch (No Installation Required)

1// Works in browsers and Node.js 18+
2// No installation needed!
3const response = await fetch('https://your-app.com/api/bookings', {
4  method: 'POST',
5  headers: {
6    'Authorization': `Bearer ${process.env.TEMPESLY_API_KEY}`,
7    'Content-Type': 'application/json'
8  },
9  body: JSON.stringify({ eventTypeId: '...', startTime: '...', inviteeEmail: '...' })
10})

Option 2: Use Axios (Enhanced Error Handling)

1# Install axios
2npm install axios
3
4# Or with yarn
5yarn add axios
6
7# Or with pnpm
8pnpm add axios
5

Create a Secure API Client Helper

Create a reusable helper function to make authenticated API calls. This centralizes your authentication logic and makes your code more maintainable.

Create /lib/tempesly-client.ts

1// lib/tempesly-client.ts
2// Server-side only - DO NOT import this in client components!
3
4/**
5 * Secure Tempesly API Client
6 * This file should only be imported in server-side code:
7 * - API routes (app/api/*/route.ts)
8 * - Server components (without 'use client')
9 * - Server actions
10 */
11
12const API_KEY = process.env.TEMPESLY_API_KEY
13const BASE_URL = process.env.TEMPESLY_BASE_URL || 'https://your-app.com'
14
15if (!API_KEY) {
16  throw new Error(
17    'TEMPESLY_API_KEY is not defined. Add it to your .env.local file.'
18  )
19}
20
21interface RequestOptions {
22  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
23  body?: any
24  headers?: Record<string, string>
25}
26
27/**
28 * Make an authenticated request to the Tempesly API
29 */
30export async function tempeslyRequest<T>(
31  endpoint: string,
32  options: RequestOptions = {}
33): Promise<T> {
34  const { method = 'GET', body, headers = {} } = options
35
36  const url = `${BASE_URL}${endpoint}`
37
38  try {
39    const response = await fetch(url, {
40      method,
41      headers: {
42        'Content-Type': 'application/json',
43        'Authorization': `Bearer ${API_KEY}`,
44        ...headers,
45      },
46      body: body ? JSON.stringify(body) : undefined,
47    })
48
49    const data = await response.json()
50
51    if (!response.ok) {
52      throw new Error(
53        data.error || `API request failed with status ${response.status}`
54      )
55    }
56
57    return data as T
58  } catch (error) {
59    console.error('Tempesly API Error:', error)
60    throw error
61  }
62}
63
64// Type definitions for better TypeScript support
65export interface EventType {
66  id: string
67  name: string
68  slug: string
69  durationMinutes: number
70  userId: string
71  createdAt: string
72  updatedAt: string
73}
74
75export interface Booking {
76  id: string
77  eventTypeId: string
78  startTime: string
79  endTime: string
80  inviteeEmail: string
81  status: 'confirmed' | 'cancelled'
82  createdAt: string
83  updatedAt: string
84}
85
86export interface AvailabilityRule {
87  id: string
88  dayOfWeek: number
89  startTime: string
90  endTime: string
91  userId: string
92  createdAt: string
93  updatedAt: string
94}
95
96export interface TimeSlot {
97  start: string
98  end: string
99  available: boolean
100}

Security Warning: This client should ONLY be used in server-side code. Never import it in components marked with 'use client' or your API key will be exposed to the browser!

6

Create Secure Server-Side API Routes

Never expose your API key to the client! Instead, create your own API routes that use the Tempesly API internally.

Example: Create Booking Route

1// app/api/create-booking/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3import { tempeslyRequest, Booking } from '@/lib/tempesly-client'
4
5export async function POST(request: NextRequest) {
6  try {
7    // Parse the request body
8    const body = await request.json()
9    const { eventTypeId, startTime, inviteeEmail } = body
10
11    // Validate input
12    if (!eventTypeId || !startTime || !inviteeEmail) {
13      return NextResponse.json(
14        { error: 'Missing required fields' },
15        { status: 400 }
16      )
17    }
18
19    // Validate email format
20    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
21    if (!emailRegex.test(inviteeEmail)) {
22      return NextResponse.json(
23        { error: 'Invalid email address' },
24        { status: 400 }
25      )
26    }
27
28    // Make the request to Tempesly API (server-side only)
29    const booking = await tempeslyRequest<Booking>('/api/bookings', {
30      method: 'POST',
31      body: {
32        eventTypeId,
33        startTime,
34        inviteeEmail,
35      },
36    })
37
38    return NextResponse.json(booking)
39  } catch (error) {
40    console.error('Booking creation failed:', error)
41    return NextResponse.json(
42      { error: error instanceof Error ? error.message : 'Internal server error' },
43      { status: 500 }
44    )
45  }
46}

Example: Get Available Slots Route

1// app/api/get-slots/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3import { tempeslyRequest, TimeSlot } from '@/lib/tempesly-client'
4
5export async function GET(request: NextRequest) {
6  try {
7    const { searchParams } = new URL(request.url)
8    const eventTypeId = searchParams.get('eventTypeId')
9    const startDate = searchParams.get('startDate')
10    const endDate = searchParams.get('endDate')
11
12    if (!eventTypeId || !startDate || !endDate) {
13      return NextResponse.json(
14        { error: 'Missing required parameters' },
15        { status: 400 }
16      )
17    }
18
19    const response = await tempeslyRequest<{ slots: TimeSlot[] }>(
20      `/api/slots?eventTypeId=${eventTypeId}&startDate=${startDate}&endDate=${endDate}`
21    )
22
23    return NextResponse.json(response)
24  } catch (error) {
25    console.error('Failed to fetch slots:', error)
26    return NextResponse.json(
27      { error: error instanceof Error ? error.message : 'Internal server error' },
28      { status: 500 }
29    )
30  }
31}

Security Checklist - You're All Set!

  • API keys stored in environment variables, never in code
  • .env files added to .gitignore to prevent accidental commits
  • API calls made through your own backend routes (API key never exposed to browser)
  • Input validation on both client and server side
  • Error handling that doesn't expose sensitive information
  • HTTPS used for all API communications

Next Steps: Explore the Components and API Reference sections to see all available features and endpoints.