Organizations & RBAC

Organizations let you manage teams, control access, and separate resources in GateFlow.

Organization Structure

Organization (Acme Corp)
├── Workspaces
│   ├── Production
│   │   ├── API Keys
│   │   ├── Provider Configs
│   │   └── Routing Rules
│   └── Development
│       └── ...
└── Members
    ├── alice@acme.com (Owner)
    ├── bob@acme.com (Admin)
    └── charlie@acme.com (Developer)

Roles and Permissions

Role Hierarchy

Role	Description
Owner	Full control, can delete organization
Admin	Manage everything except billing and org deletion
Developer	Use API keys, view analytics
Viewer	Read-only access to analytics

Permission Matrix

Action	Owner	Admin	Developer	Viewer
Delete organization	✓
Manage billing	✓
Invite members	✓	✓
Remove members	✓	✓
Create API keys	✓	✓
Revoke API keys	✓	✓
Configure providers	✓	✓
Edit routing rules	✓	✓
Use API keys	✓	✓	✓
View analytics	✓	✓	✓	✓
Export data	✓	✓	✓

Workspaces

Workspaces isolate resources within an organization.

Common Setup

Organization
├── Production Workspace
│   ├── Production API keys
│   ├── Production provider configs (with prod API keys)
│   └── Strict routing rules
├── Staging Workspace
│   ├── Staging API keys
│   └── Staging provider configs
└── Development Workspace
    ├── Development API keys
    └── Relaxed limits for testing

Creating Workspaces

curl -X POST https://api.gateflow.ai/v1/management/workspaces \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "Production environment"
  }'

Workspace Isolation

• API keys belong to a workspace
• Provider configs are workspace-specific
• Analytics are filtered by workspace
• No cross-workspace access

Managing Members

Invite a Member

curl -X POST https://api.gateflow.ai/v1/management/members \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "role": "developer",
    "workspaces": ["ws_production", "ws_staging"]
  }'

Update Role

curl -X PATCH https://api.gateflow.ai/v1/management/members/member_123 \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Remove Member

curl -X DELETE https://api.gateflow.ai/v1/management/members/member_123 \
  -H "Authorization: Bearer gw_prod_admin_key"

WARNING

When removing members, consider rotating API keys they may have accessed.

Service Accounts

For automated systems that need API access:

Create Service Account

curl -X POST https://api.gateflow.ai/v1/management/service-accounts \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "role": "developer",
    "workspaces": ["ws_staging"]
  }'

Response:

{
  "id": "sa_abc123",
  "name": "CI/CD Pipeline",
  "api_key": "gw_prod_sa_abc123...",
  "role": "developer"
}

Service Account Best Practices

1. Minimal Permissions: Only grant what's needed
2. Workspace Scoping: Limit to specific workspaces
3. Regular Rotation: Rotate keys periodically
4. Audit Logging: Review service account activity

Single Sign-On (SSO)

Enterprise plans support SSO integration.

Supported Providers

• Okta
• Azure AD
• Google Workspace
• Generic SAML 2.0
• Generic OIDC

Configuration

1. Go to Settings → Security → SSO
2. Select your identity provider
3. Enter configuration details:
   • SSO URL
   • Certificate
   • Entity ID
4. Test the connection
5. Enable SSO enforcement (optional)

SSO Enforcement

When enabled:

• All members must authenticate via SSO
• Password login is disabled
• New members are auto-provisioned from IdP

Audit Logging

All organization actions are logged:

curl https://api.gateflow.ai/v1/management/audit-log \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -G -d "limit=50"

Response:

{
  "events": [
    {
      "id": "evt_123",
      "type": "member.invited",
      "actor": {
        "id": "user_456",
        "email": "admin@company.com"
      },
      "target": {
        "type": "member",
        "email": "newuser@company.com"
      },
      "timestamp": "2024-01-15T10:30:00Z",
      "ip_address": "203.0.113.42"
    }
  ]
}

Audit Event Types

Event	Description
member.invited	Member invitation sent
member.joined	Member accepted invitation
member.removed	Member removed from org
member.role_changed	Member role updated
api_key.created	API key created
api_key.revoked	API key revoked
provider.configured	Provider settings changed
sso.enabled	SSO enabled

Multi-Organization Access

Users can belong to multiple organizations:

curl https://api.gateflow.ai/v1/management/organizations \
  -H "Authorization: Bearer user_access_token"

Response:

{
  "organizations": [
    {
      "id": "org_acme",
      "name": "Acme Corp",
      "role": "admin"
    },
    {
      "id": "org_consulting",
      "name": "Consulting LLC",
      "role": "developer"
    }
  ]
}

Switching Organizations

API keys are organization-specific. Use the appropriate key for each org.

Best Practices

1. Principle of Least Privilege

Start with minimal permissions and add as needed:

New employee → Viewer
After training → Developer
After promotion → Admin

2. Workspace Separation

Keep production isolated:

Production: Only admins + automated systems
Staging: Developers can test
Development: Open for experimentation

3. Regular Access Reviews

Quarterly review:

• Remove inactive members
• Downgrade unnecessary permissions
• Rotate service account keys

4. Offboarding Checklist

When someone leaves:

1. Remove from organization
2. Rotate any keys they created
3. Review audit log for their activity
4. Update any shared credentials

Next Steps

• API Keys - Key management
• Provider Configuration - Set up providers