openapi: 3.1.0
info:
  title: Airtable SCIM 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
externalDocs:
  description: Airtable SCIM API Documentation
  url: https://airtable.com/developers/web/api/scim-overview
servers:
- url: https://airtable.com/scim/v2
  description: Airtable SCIM v2 production server
security:
- bearerAuth: []
tags:
- name: Groups
  description: SCIM group provisioning and management
- name: Users
  description: SCIM user provisioning and management
paths:
  /Users:
    get:
      operationId: listScimUsers
      summary: Airtable List SCIM Users
      description: >-
        Returns a paginated list of SCIM user resources. Supports filtering
        by user attributes and pagination using startIndex and count
        parameters per the SCIM 2.0 specification.
      tags:
      - Users
      parameters:
      - name: filter
        in: query
        required: false
        description: >-
          SCIM filter expression (e.g., userName eq "user@example.com").
          Supports eq operator on userName.
        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 user resources.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createScimUser
      summary: Airtable Create a SCIM User
      description: >-
        Provisions a new user in Airtable through the SCIM protocol. The
        user will be added to the enterprise account. SSO must be configured
        as Airtable does not allow setting passwords through SCIM.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUserCreateRequest'
      responses:
        '201':
          description: The newly created SCIM user resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A user with the same userName already exists.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Users/{userId}:
    get:
      operationId: getScimUser
      summary: Airtable Get a SCIM User
      description: >-
        Retrieves a single SCIM user resource by its unique identifier.
        Returns the complete user profile including name, email, and active
        status.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: The requested SCIM user resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '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: replaceScimUser
      summary: Airtable Replace a SCIM User
      description: >-
        Replaces a SCIM user resource entirely. All attributes are
        overwritten with the values in the request body. This is a full
        replacement, not a partial update.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUserCreateRequest'
      responses:
        '200':
          description: The replaced SCIM user resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '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: updateScimUser
      summary: Airtable Update a SCIM User (partial)
      description: >-
        Partially updates a SCIM user resource using SCIM PATCH operations.
        Supports add, replace, and remove operations on user attributes.
        Commonly used to activate or deactivate users.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
      responses:
        '200':
          description: The updated SCIM user resource.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '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: deleteScimUser
      summary: Airtable Delete a SCIM User
      description: >-
        Permanently deletes a SCIM user resource from the enterprise account.
        The user will lose access to all Airtable resources associated with
        the enterprise.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '204':
          description: The user 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
  /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:
  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.
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: The unique identifier of the SCIM user resource.
      schema:
        type: string
    groupId:
      name: groupId
      in: path
      required: true
      description: The unique identifier of the SCIM group resource.
      schema:
        type: string
  schemas:
    ScimUser:
      type: object
      description: A SCIM 2.0 User resource representing a provisioned user.
      properties:
        schemas:
          type: array
          description: The SCIM schema URIs for this resource.
          items:
            type: string
          default:
          - urn:ietf:params:scim:schemas:core:2.0:User
        id:
          type: string
          description: The unique identifier for the SCIM user resource.
        userName:
          type: string
          description: The unique username for the user, typically an email address.
        name:
          type: object
          description: The user's name components.
          properties:
            givenName:
              type: string
              description: The user's first name.
            familyName:
              type: string
              description: The user's last name.
        emails:
          type: array
          description: The user's email addresses.
          items:
            type: object
            properties:
              value:
                type: string
                format: email
                description: The email address.
              type:
                type: string
                description: The type of email (e.g., work).
              primary:
                type: boolean
                description: Whether this is the primary email.
        active:
          type: boolean
          description: Whether the user account is active.
        title:
          type: string
          description: The user's job title.
        meta:
          $ref: '#/components/schemas/ScimMeta'
      required:
      - schemas
      - id
      - userName
      - active
    ScimUserCreateRequest:
      type: object
      description: Request body for creating or replacing a SCIM user.
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
          - urn:ietf:params:scim:schemas:core:2.0:User
        userName:
          type: string
          description: The unique username for the user, typically an email address.
        name:
          type: object
          properties:
            givenName:
              type: string
              description: The user's first name.
            familyName:
              type: string
              description: The user's last name.
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              type:
                type: string
              primary:
                type: boolean
        active:
          type: boolean
          description: Whether the user account should be active.
          default: true
        title:
          type: string
          description: The user's job title.
      required:
      - schemas
      - userName
    ScimUserListResponse:
      type: object
      description: A SCIM 2.0 ListResponse containing user 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 user resources.
          items:
            $ref: '#/components/schemas/ScimUser'
      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
    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
    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
    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
    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.
    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.
  responses:
    Unauthorized:
      description: SCIM authentication token is missing or invalid.
      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'
    BadRequest:
      description: The request body is malformed or contains invalid data.
      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'