Workspaces

Workspaces are the top-level container in SpatialFlow, providing data isolation and centralized management. Every user belongs to exactly one workspace, which acts as the security boundary for all geofences, workflows, devices, and API keys.

What is a Workspace?

A workspace is your private environment within SpatialFlow. All your resources—geofences, workflows, devices, and webhooks—belong to your workspace and are isolated from other users.

Key characteristics:

• Each user account belongs to a workspace
• Workspaces support multiple users with role-based access control
• All resources are automatically scoped to your workspace
• API keys inherit your workspace context
• Complete data isolation from other workspaces

Workspace Properties

Every workspace has these core properties:

Property	Description
Workspace ID	Unique UUID identifier (immutable)
Name	Human-readable name (1-255 characters)
Slug	URL-friendly identifier with unique suffix
Contact Email	Email for support and notifications
Created At	Timestamp when workspace was created

Creating Workspaces

Workspaces are automatically created during signup:

1. You register with your name and email
2. SpatialFlow creates a workspace named "[Your Name]'s Workspace"
3. Your contact email is set to your account email
4. You're ready to create geofences and workflows

Viewing Your Workspace

Get your workspace details via the API:

curl https://api.spatialflow.io/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "id": "org_abc123",
  "name": "Jane Smith's Workspace",
  "slug": "jane-smiths-workspace-a1b2c3",
  "billing_email": "jane@example.com",
  "created_at": "2025-11-10T10:00:00Z",
  "updated_at": "2025-11-10T10:00:00Z"
}

Updating Your Workspace

Update workspace settings via the API:

curl -X PUT https://api.spatialflow.io/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Logistics",
    "billing_email": "contact@acme.com"
  }'

API Keys

API keys are your primary method for programmatic access. All keys are scoped to your workspace.

Creating an API Key

curl -X POST https://api.spatialflow.io/api/v1/accounts/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "rate_limit_per_hour": 1000
  }'

caution

The full API key is only shown once during creation. Store it securely—SpatialFlow only stores a cryptographic hash.

Managing API Keys

# List all keys
curl https://api.spatialflow.io/api/v1/accounts/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Rotate a key
curl -X POST https://api.spatialflow.io/api/v1/accounts/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Delete a key
curl -X DELETE https://api.spatialflow.io/api/v1/accounts/api-keys/{key_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Best Practices

• Use descriptive names: "Production Backend", "Mobile App v2"
• Set expiration dates and rotate keys regularly
• Store keys in environment variables, never in code
• Create separate keys for different applications

Data Isolation

Your workspace provides complete data isolation:

• All resources belong exclusively to your workspace
• API requests cannot access other workspaces
• Database queries are automatically scoped to your workspace

Team Members & Roles

Workspaces support multiple users with role-based access control (RBAC). Invite team members and assign roles to control what they can do within your workspace.

Role Hierarchy

Role	Description
Owner	Full control over the workspace, members, billing, and all resources
Manager	Manage members, devices, geofences, and workflows. Cannot change billing or delete the workspace
Field Worker	Limited to their own device and location data. Can view assigned geofences

Inviting Members

Invite a new team member via the Dashboard (Settings → Team Members → Invite Member) or the API:

curl -X POST https://api.spatialflow.io/api/v1/workspaces/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "manager"
  }'

Managing Members

# List workspace members
curl https://api.spatialflow.io/api/v1/workspaces/members \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Update a member's role
curl -X PATCH https://api.spatialflow.io/api/v1/workspaces/members/{user_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "field_worker"}'

# Remove a member
curl -X DELETE https://api.spatialflow.io/api/v1/workspaces/members/{user_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Privacy & Data Erasure

SpatialFlow provides GDPR Article 17-compliant data erasure tools, accessible via the Dashboard (Settings → Privacy Tools) or the API.

Erasure Scopes

Scope	Description
Organization	Delete all location data for the entire workspace
Device	Delete location data for a specific device
Date Range	Delete location data within a specific time window
Tag	Delete location data matching a metadata tag

Requesting Erasure

curl -X POST https://api.spatialflow.io/api/v1/accounts/privacy/erasure \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "device",
    "device_ids": ["truck-005"],
    "dry_run": true
  }'

Set dry_run: true to preview what data would be deleted without actually removing it.

Checking Erasure Status

curl https://api.spatialflow.io/api/v1/accounts/privacy/erasure/{job_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

API Reference

Key workspace endpoints:

Endpoint	Method	Description
/api/v1/workspaces	GET	Get your workspace details
/api/v1/workspaces	PUT	Update workspace settings
/api/v1/workspaces/members	GET	List workspace members
/api/v1/workspaces/members/{user_id}	PATCH	Update member role
/api/v1/workspaces/members/{user_id}	DELETE	Remove member
/api/v1/workspaces/invitations	POST	Invite a new member
/api/v1/accounts/api-keys	POST	Create API key
/api/v1/accounts/api-keys	GET	List API keys
/api/v1/accounts/api-keys/{id}/rotate	POST	Rotate API key
/api/v1/accounts/api-keys/{id}	DELETE	Delete API key
/api/v1/accounts/privacy/erasure	POST	Request data erasure
/api/v1/accounts/privacy/erasure/{job_id}	GET	Check erasure status

See the API Reference for complete details.

Next Steps

• Quick Start Guide - Set up your first workflow
• Geofences - Create geofences in your workspace
• Workflows - Automate actions
• Authentication - Learn about JWT and API keys