Skip to main content

​
API Authentication

Skaala supports two authentication methods for API access:

API Keys

Recommended for integrations Simple bearer token authentication with granular scopes

Stack Auth Cookies

For web dashboard Session-based authentication for browser access

​
API Key Authentication

​
Creating an API Key

​
Using API Keys

API keys can be provided in two ways:

​
Available Scopes

API keys support granular permissions to limit access:
  • read:bookings - View bookings and appointments
  • read:contacts - View contacts and customer profiles
  • read:calls - View call history and transcripts
  • read:services - View services and pricing
  • read:staff - View staff information
  • write:bookings - Create and update bookings
  • write:contacts - Create and update contacts
  • write:calls - Create call records
  • webhooks:manage - Subscribe to and manage webhooks
Best Practice: Use the minimum scopes required for your integration. For read-only integrations, only request read:* scopes.

​
Security Best Practices

Environment Variables

Never commit API keys to version control. Use environment variables:
export SKAALA_API_KEY=sk_live_...

Minimal Scopes

Grant only the permissions needed. Read-only when possible.

Set Expiration

Default: 365 days. Rotate keys regularly for production.

Monitor Usage

Check “Last Used” timestamp in dashboard to detect unused keys.

​
Error Responses

​
401 Unauthorized
error
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
Common causes:
  • API key doesn’t exist or has been revoked
  • API key has expired
  • Invalid format (must start with sk_live_)
​
403 Forbidden
error
{
  "error": "forbidden",
  "message": "Insufficient scopes"
}
Common causes:
  • API key lacks required scope for endpoint
  • User no longer has team access
  • Team membership revoked

​
Complete Example

Here’s a complete PowerShell example showing both GET and POST requests:
PowerShell
$BaseUrl = "https://www.skaala.ai"
$ApiKey = $env:SKAALA_API_KEY

# List bookings
$bookings = Invoke-RestMethod -Method Get `
  -Uri "$BaseUrl/api/v1/bookings" `
  -Headers @{ "Authorization" = "Bearer $ApiKey" }

Write-Output "Found $($bookings.meta.total) bookings"

# Create a booking
$body = @{
  service_id = "svc_abc123"
  start_time = "2025-01-15T10:00:00Z"
  contact = @{
    name = "Anna Svensson"
    email = "anna@example.se"
    phone = "+46701234567"
  }
  notes = "First-time customer"
} | ConvertTo-Json

$newBooking = Invoke-RestMethod -Method Post `
  -Uri "$BaseUrl/api/v1/bookings" `
  -Headers @{
    "Authorization" = "Bearer $ApiKey"
    "Content-Type" = "application/json"
  } `
  -Body $body

Write-Output "Booking created: $($newBooking.data.id)"

​
Troubleshooting

Check:
  1. Key format must start with sk_live_
  2. Key hasn’t been revoked in dashboard
  3. Key hasn’t expired
  4. Correct team ID in URL path
Check:
  1. Key has required scope (e.g., write:bookings for POST)
  2. User still has team membership
  3. Team ID matches key’s team
Check:
  1. You have admin or owner role
  2. Authenticated via dashboard cookies
  3. Team ID is correct in the URL
If you’re currently using cookie authentication and want to switch: 
Invoke-RestMethod -Uri "$BaseUrl/api/v1/bookings" `
  -Headers @{ "Cookie" = "stack-access-token=..." }
Benefits of API keys:
  • ✅ No cookie refresh handling required
  • ✅ Simpler authentication flow
  • ✅ Granular permissions via scopes
  • ✅ Easy rotation and revocation
  • ✅ Audit trail with “last used” timestamp

​
Next Steps

Quickstart

Make your first API call

API Reference

Browse all endpoints

Rate Limits

Understand API limits

Webhooks

Set up real-time notifications