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()
);

Column	Description
`id`	Unique identifier
`name`	Human-readable name
`api_key_hash`	SHA-256 hash of the API key
`role_id`	Associated role for permissions
`is_active`	Set to false to revoke access
`last_used_at`	Tracks last authentication

Security Best Practices

Rotate Keys Regularly

Create new service accounts periodically and revoke old ones to minimize exposure from compromised keys.

Use Least Privilege

Assign the minimum role required. Use robot role for automated systems instead of superadmin.

Monitor Usage

Regularly check last_used_at to identify unused accounts that should be revoked.

Secure Storage

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:

Verify the key is correct (only shown once at creation)
Check is_active in the database
Verify role_id is set

Getting Started

Architecture

Authentication

Operations

Equipment

Service Accounts

Service Accounts

Overview

Creating a Service Account

Managing Service Accounts

Using a Service Account

Authentication

Making API Calls

Database Schema

Security Best Practices

Troubleshooting

API Key Not Working

​Service Accounts

​Overview

​Creating a Service Account

​Managing Service Accounts

​Using a Service Account

​Authentication

​Making API Calls

​Database Schema

​Security Best Practices

​Troubleshooting

​API Key Not Working

Service Accounts

Overview

Creating a Service Account

Managing Service Accounts

Using a Service Account

Authentication

Making API Calls

Database Schema

Security Best Practices

Troubleshooting

API Key Not Working