Skip to main content

​
Service Accounts

Service accounts enable automated systems (robots, scripts, integrations) to authenticate with Switchyard using API keys.

​
Overview

Service accounts provide:
  • API Key Authentication: No user interaction required
  • Role-based Permissions: Inherit permissions from assigned role
  • Audit Trail: Track last usage timestamp
  • Secure Storage: API keys are hashed before storage

​
Creating a Service Account

Use the CLI tool: 
npx ts-node scripts/create-service-account.ts create \
  --name "Inventory Scanner Bot" \
  --role robot
Output: 
=== Service Account Created ===
ID: 123e4567-e89b-12d3-a456-426614174000
Name: Inventory Scanner Bot
Role: robot

API Key (save this - it will not be shown again):

  sk_robot_a1b2c3d4e5f6...

================================
The API key is only shown once at creation. Store it securely - it cannot be retrieved later.

​
Managing Service Accounts

# List all service accounts
npx ts-node scripts/create-service-account.ts list

# Revoke a service account (deactivate)
npx ts-node scripts/create-service-account.ts revoke <id>

# Delete a service account
npx ts-node scripts/create-service-account.ts delete <id>

​
Using a Service Account

​
Authentication

# Authenticate with the API key
curl -X POST 'https://api.switchyard.run/auth/user/supabase' \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk_robot_a1b2c3d4e5f6..."}'

​
Making API Calls

# Use the returned token for subsequent requests
curl 'https://api.switchyard.run/scanner/inventory/scan' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"barcode": "012345678901"}'

​
Database Schema

CREATE TABLE public.service_accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  api_key_hash VARCHAR(255) NOT NULL,
  role_id UUID REFERENCES public.roles(id),
  is_active BOOLEAN DEFAULT TRUE,
  last_used_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
ColumnDescription
idUnique identifier
nameHuman-readable name
api_key_hashSHA-256 hash of the API key
role_idAssociated role for permissions
is_activeSet to false to revoke access
last_used_atTracks last authentication

​
Security Best Practices

Create new service accounts periodically and revoke old ones to minimize exposure from compromised keys.
Assign the minimum role required. Use robot role for automated systems instead of superadmin.
Regularly check last_used_at to identify unused accounts that should be revoked.
Store API keys in environment variables or secrets managers, never in code.

​
Troubleshooting

​
API Key Not Working

Possible causes:
  • Typo in API key
  • Service account is inactive (is_active = false)
  • Role not assigned
Solutions:
  1. Verify the key is correct (only shown once at creation)
  2. Check is_active in the database
  3. Verify role_id is set