Airtable Groups API

openapi: 3.2.0
info:
  title: Airtable SCIM Groups API
  description: The Airtable SCIM API supports the System for Cross-domain Identity Management (SCIM 2.0) specification for automated user and group provisioning. It enables identity providers like Okta and Microsoft Entra ID to manage user accounts and group memberships programmatically. SCIM is available for Enterprise License Agreement (ELA) and CLAIM enterprise accounts with SSO configured.
  version: 2.0.0
  contact:
    name: Airtable
    url: https://airtable.com/developers
    email: support@airtable.com
  license:
    name: Proprietary
    url: https://airtable.com/tos
  termsOfService: https://airtable.com/tos
servers:
- url: https://airtable.com/scim/v2
  description: Airtable SCIM v2 production server
security:
- bearerAuth: []
tags:
- name: Groups
  description: SCIM group provisioning and management
paths:
  /Groups:
    get:
      operationId: listScimGroups
      summary: Airtable List SCIM Groups
      description: Returns a paginated list of SCIM group resources. Supports filtering by group display name and pagination using startIndex and count.
      tags:
      - Groups
      parameters:
      - name: filter
        in: query
        required: false
        description: SCIM filter expression (e.g., displayName eq "Engineering").
        schema:
          type: string
      - name: startIndex
        in: query
        required: false
        description: The 1-based index of the first result to return.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: count
        in: query
        required: false
        description: The maximum number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: A SCIM ListResponse containing group resources.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimGroupListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createScimGroup
      summary: Airtable Create a SCIM Group
      description: Creates a new SCIM group in the enterprise account. Groups can contain user members and are used for access management.
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimGroupCreateRequest'
      responses:
        '201':
          description: The newly created SCIM group resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A group with the same displayName already exists.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Groups/{groupId}:
    get:
      operationId: getScimGroup
      summary: Airtable Get a SCIM Group
      description: Retrieves a single SCIM group resource by its unique identifier, including its member list.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      responses:
        '200':
          description: The requested SCIM group resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ScimNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: replaceScimGroup
      summary: Airtable Replace a SCIM Group
      description: Replaces a SCIM group resource entirely with the provided data. The complete member list must be included in the request.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimGroupCreateRequest'
      responses:
        '200':
          description: The replaced SCIM group resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ScimNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateScimGroup
      summary: Airtable Update a SCIM Group (partial)
      description: Partially updates a SCIM group resource using SCIM PATCH operations. Commonly used to add or remove members from the group without replacing the entire resource.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
      responses:
        '200':
          description: The updated SCIM group resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ScimNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteScimGroup
      summary: Airtable Delete a SCIM Group
      description: Permanently deletes a SCIM group from the enterprise account. Members are not deleted but are removed from the group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      responses:
        '204':
          description: The group was successfully deleted. No content returned.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ScimNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    BadRequest:
      description: The request body is malformed or contains invalid data.
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimError'
    Forbidden:
      description: The authenticated token does not have SCIM provisioning permission.
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimError'
    Unauthorized:
      description: SCIM authentication token is missing or invalid.
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimError'
    ScimNotFound:
      description: The requested SCIM resource was not found.
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimError'
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimError'
  schemas:
    ScimGroupCreateRequest:
      type: object
      description: Request body for creating or replacing a SCIM group.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        displayName:
          type: string
          description: The display name of the group.
        members:
          type: array
          description: The initial members of the group.
          items:
            type: object
            properties:
              value:
                type: string
                description: The ID of the member user.
      required:
      - schemas
      - displayName
    ScimError:
      type: object
      description: A SCIM 2.0 error response.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:api:messages:2.0:Error
        detail:
          type: string
          description: A human-readable description of the error.
        status:
          type: string
          description: The HTTP status code as a string.
        scimType:
          type: string
          description: The SCIM error type.
    ScimPatchRequest:
      type: object
      description: A SCIM 2.0 PATCH request with one or more operations.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          description: The list of PATCH operations to apply.
          items:
            type: object
            properties:
              op:
                type: string
                description: The operation type.
                enum:
                - add
                - replace
                - remove
              path:
                type: string
                description: The attribute path to operate on.
              value:
                description: The value to set for add and replace operations.
            required:
            - op
      required:
      - schemas
      - Operations
    ScimGroupListResponse:
      type: object
      description: A SCIM 2.0 ListResponse containing group resources.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: The total number of results matching the query.
        itemsPerPage:
          type: integer
          description: The number of results returned in this page.
        startIndex:
          type: integer
          description: The 1-based index of the first result in this page.
        Resources:
          type: array
          description: The list of SCIM group resources.
          items:
            $ref: '#/components/schemas/ScimGroup'
      required:
      - schemas
      - totalResults
      - Resources
    ScimGroup:
      type: object
      description: A SCIM 2.0 Group resource representing a user group.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        id:
          type: string
          description: The unique identifier for the SCIM group resource.
        displayName:
          type: string
          description: The display name of the group.
        members:
          type: array
          description: The members of the group.
          items:
            type: object
            properties:
              value:
                type: string
                description: The ID of the member user.
              display:
                type: string
                description: The display name of the member.
        meta:
          $ref: '#/components/schemas/ScimMeta'
      required:
      - schemas
      - id
      - displayName
    ScimMeta:
      type: object
      description: SCIM resource metadata.
      properties:
        resourceType:
          type: string
          description: The type of resource (User or Group).
        created:
          type: string
          format: date-time
          description: The time when the resource was created.
        lastModified:
          type: string
          format: date-time
          description: The time when the resource was last modified.
  parameters:
    groupId:
      name: groupId
      in: path
      required: true
      description: The unique identifier of the SCIM group resource.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: SCIM API uses Bearer token authentication with a SCIM API token generated from the Airtable enterprise admin panel.
externalDocs:
  description: Airtable SCIM API Documentation
  url: https://airtable.com/developers/web/api/scim-overview