Organizations

Model complex B2B structures with multi-level organization hierarchies. Support holding companies, subsidiaries, departments, and teams.

Organization Structure

Organizations in AccessIQ represent your customers. Each organization is a complete tenant with isolated data, users, and configurations.

Organization Hierarchy Example

Acme Corporation (Root)

├── North America Division

├── Engineering Dept

├── Frontend Team

└── Backend Team

└── Sales Dept

└── Europe Division

└── Engineering Dept

5-Level Hierarchy

AccessIQ supports up to 5 levels of organization nesting, allowing you to model even the most complex enterprise structures.

Creating Organizations

Create Organization APIbash

curl -X POST https://api.accessiq.io/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "displayName": "Acme Corp",
    "plan": "professional",
    "settings": {
      "allowUserInvites": true,
      "requireMfa": false,
      "sessionTimeout": 3600
    },
    "metadata": {
      "industry": "technology",
      "size": "enterprise"
    }
  }'

Child Organizations

Create hierarchical structures by specifying a parent organization:

Create Child Organizationbash

curl -X POST https://api.accessiq.io/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Department",
    "slug": "acme-corp-engineering",
    "parentId": "org_acme_corp_123",
    "inheritSettings": true,
    "inheritRoles": true
  }'

Inheritance Options

Settings Inheritance

Child organizations can inherit security settings, session policies, and MFA requirements from their parent.

Role Inheritance

Roles defined at the parent level can be automatically available to child organizations.

IdP Inheritance

Child organizations can use the parent's identity provider or configure their own.

Organization Settings

Each organization can have customized settings:

Organization Settingstypescript

interface OrganizationSettings {
  // Security
  requireMfa: boolean
  mfaMethods: ('totp' | 'sms' | 'email' | 'passkey')[]
  passwordPolicy: {
    minLength: number
    requireUppercase: boolean
    requireNumbers: boolean
    requireSymbols: boolean
  }

  // Sessions
  sessionTimeout: number // seconds
  maxConcurrentSessions: number

  // User Management
  allowUserInvites: boolean
  allowSelfRegistration: boolean
  domainRestrictions: string[] // e.g., ['@acme.com']

  // Branding
  logoUrl: string
  primaryColor: string
  customDomain: string
}

Cross-Organization Access

Users can belong to multiple organizations with different roles in each:

User Organization Membershipstypescript

// User can have different roles in different orgs
const user = {
  id: 'user_123',
  email: 'john@example.com',
  memberships: [
    {
      organizationId: 'org_acme',
      roles: ['admin'],
      permissions: ['*']
    },
    {
      organizationId: 'org_techstart',
      roles: ['viewer'],
      permissions: ['read:*']
    }
  ]
}

// Switch organization context
const switchOrganization = async (orgId: string) => {
  const response = await fetch('/api/auth/switch-org', {
    method: 'POST',
    body: JSON.stringify({ organizationId: orgId })
  })
  // Returns new JWT with org-specific claims
}

Best Practices

Use slugs that are URL-friendly and unique
Set up inheritance to reduce configuration overhead
Use metadata to store custom attributes
Configure domain restrictions for enterprise customers