Crowd.dev Organizations API

openapi: 3.2.0
info:
  title: CDP Public Organizations API
  version: 1.0.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: "Public REST API for the Community Data Platform (CDP). Provides transactional endpoints for identity verification, work experience management, project affiliations, and contributor lookup.\n\nTwo authentication methods are supported depending on the endpoint:\n- **OAuth 2.0 Bearer (Auth0)** — used by LFX One for member, organization,\n  and affiliation management endpoints.\n\n- **Static API Key** — bearer token with scopes managed in the CDP database.\n"
servers:
- url: https://cm.lfx.dev/api/v1
  description: Production
- url: https://lf-staging.crowd.dev/api/v1
  description: Staging
security: []
tags:
- name: Organizations
  description: Look up and create organizations.
paths:
  /organizations:
    get:
      operationId: getOrganization
      summary: Look up an organization by domain or name
      description: 'Provide domain, name, or both. When both are provided, the domain and name must belong to the same organization. If multiple organizations match, the most active one is returned.

        '
      tags:
      - Organizations
      security:
      - OAuth2Bearer:
        - read:organizations
      parameters:
      - name: domain
        in: query
        required: false
        description: Primary domain of the organization.
        schema:
          type: string
          minLength: 1
        example: linuxfoundation.org
      - name: name
        in: query
        required: false
        description: Exact display name of the organization.
        schema:
          type: string
          minLength: 1
        example: Linux Foundation
      responses:
        '200':
          description: Organization found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Linux Foundation
                domain: linuxfoundation.org
                logo: https://example.com/logo.png
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No organization found for the given domain or name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: NOT_FOUND
                  message: Organization not found
    post:
      operationId: createOrganization
      summary: Create an organization
      description: 'Create a new organization with a verified primary domain. If an organization with the same domain already exists, it returns the existing one.

        '
      tags:
      - Organizations
      security:
      - OAuth2Bearer:
        - write:organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - domain
              - source
              - logo
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Display name of the organization.
                domain:
                  type: string
                  minLength: 1
                  description: Primary domain of the organization.
                source:
                  type: string
                  minLength: 1
                  description: Source system creating the organization.
                logo:
                  type: string
                  format: uri
                  description: URL of the organization's logo.
            example:
              name: Acme Corp
              domain: acme.com
              source: lfxOne
              logo: https://example.com/logo.png
      responses:
        '201':
          description: Organization created (or existing one returned).
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - name
                - domain
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  domain:
                    type: string
                    description: Verified primary domain of the organization.
                  logo:
                    type:
                    - string
                    - 'null'
                    description: URL of the organization logo.
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Acme Corp
                domain: acme.com
                logo: https://example.com/logo.png
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    BadRequest:
      description: Invalid request body or query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: BAD_REQUEST
              message: Validation failed
    Forbidden:
      description: Authentication valid but insufficient scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: INSUFFICIENT_SCOPE
              message: Insufficient scope for this operation
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing authentication
  schemas:
    HttpError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error description.
    Organization:
      type: object
      required:
      - id
      - name
      - domain
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Display name of the organization.
        domain:
          type: string
          description: Verified primary domain.
        logo:
          type: string
          description: URL of the organization logo. Only present if available.
  securitySchemes:
    OAuth2Bearer:
      type: oauth2
      description: 'OAuth 2.0 client credentials flow via Auth0. The consuming service obtains a JWT using its client ID and secret, then passes it as `Authorization: Bearer <token>`

        '
      flows:
        clientCredentials:
          tokenUrl: https://linuxfoundation.auth0.com/oauth/token
          scopes:
            read:members: Read member profiles
            write:members: Create member profiles
            read:member-identities: Read member identities
            write:member-identities: Create and verify member identities
            read:maintainer-roles: Read maintainer roles
            read:work-experiences: Read work experiences
            write:work-experiences: Create, update, verify, and delete work experiences
            read:project-affiliations: Read project affiliations
            write:project-affiliations: Override project affiliations
            read:organizations: Look up organizations
            write:organizations: Create organizations
    StaticApiKey:
      type: http
      scheme: bearer
      description: 'Static API key — pass as `Authorization: Bearer <token>`. Keys are managed in the CDP database with SHA-256 hashing, expiration, and revocation support.

        '