Overview

Organization routes pull data from the normalized users, organizations, and organization_memberships tables. Every route requires authentication via getRequestSession().

GET /api/organizations

File: app/api/organizations/route.ts

Lists all organizations the authenticated user belongs to, enriched with installation status.

Response

{
  "organizations": [
    {
      "id": 67890,
      "login": "my-org",
      "name": "My Organization",
      "avatarUrl": "https://avatars.githubusercontent.com/u/67890",
      "viewerCanAdminister": true,
      "hasAppInstalled": true,
      "installationId": 12345,
      "repositoryCount": null,
      "repositorySelection": null,
      "suspendedAt": null
    }
  ]
}

Fields

Error responses

Frontend hook

import { useOrganizationsQuery } from '@/hooks/queries';
 
const { data: organizations, isLoading } = useOrganizationsQuery();

GET /api/organizations/[login]

File: app/api/organizations/[login]/route.ts

Get detailed information about a specific organization, including installation metadata.

Parameters

Response

{
  "organization": {
    "id": 67890,
    "login": "my-org",
    "name": "My Organization",
    "avatarUrl": "https://avatars.githubusercontent.com/u/67890",
    "viewerCanAdminister": true,
    "hasAppInstalled": true,
    "installationId": 12345,
    "repositoryCount": 42,
    "repositorySelection": "all",
    "suspendedAt": null
  }
}

If the organization has an installation, the route queries InstallationService.getInstallationForOrg() to fetch cached repository count, selection, and suspension status from github_installations.

Error responses

Frontend hook

import { useOrganizationDetailQuery } from '@/hooks/queries';
 
const { data: org, isLoading } = useOrganizationDetailQuery('my-org');

POST /api/organizations/[login]/mass-invite

File: app/api/organizations/[login]/mass-invite/route.ts

Bulk-invite GitHub users to an organization. Requires admin access.

Request body

{
  "userLogins": ["alice", "bob", "charlie"]
}

Response

{
  "succeeded": ["alice", "bob"],
  "failed": [{ "login": "charlie", "error": "Not Found" }]
}

Authorization

You must be an admin (viewerCanAdminister = true in organization_memberships).

Implementation

1. Validates you’re an admin of the target org
2. Resolves each username to a GitHub user ID via users.getByUsername
3. Sends organization invitations via orgs.createInvitation
4. Returns per-user results

Error responses

For a deep dive into the mass-invite pipeline (concurrency, GraphQL + REST, per-user error handling), see Mass Invite API.

Related

• Mass Invite API — validation pipeline, edge cases, rate limiting
• Auth Routes — session authentication
• Database Schema — organizations, organization_memberships tables