# SCIM

Retrieve, add, and modify users and groups.

We support a subset of the specification for [System for Cross-domain Identity Management](https://datatracker.ietf.org/wg/scim/about/), or SCIM. We support a [select list of user attributes](/developers/web/api/scim-overview.md#scim-user-objects).

**Note:** SCIM user management is only available for the [Business, Enterprise, and Enterprise Scale plans](/developers/web/api/billing-plans.md#current), while SCIM group management is only available for the [Enterprise and Enterprise Scale plans](/developers/web/api/billing-plans.md#current). SSO is a prerequisite for creating and updating users, since we don't allow setting passwords with SCIM. Only [managed users](/developers/web/api/org-management-glossary.md#managed-user) can be retrieved and managed using the SCIM API.

## SCIM User Objects

| Airtable Field                                                             | SCIM Attribute          | Required |
| -------------------------------------------------------------------------- | ----------------------- | -------- |
| `id`, `userId`                                                             | `id`                    | False    |
| `email` (or the SSO NameID, when the IdP has `emailAttribute` configured)  | `userName`              | True     |
| `email` (required when `userName` is the SSO NameID, not the user's email) | `emails[primary].value` | False    |
| `firstName`                                                                | `givenName`             | True     |
| `lastName`                                                                 | `familyName`            | True     |
| `state` ("provisioned" \| "deactivated")                                   | `active` (boolean)      | True     |

**Email mapping.** In most configurations, `userName` is the user's email address and becomes the `email` field in Airtable. When the user's SSO identity provider has `emailAttribute` configured, `userName` is the IdP-supplied SSO identifier (which may be non-email, up to 255 characters) and the user's email is taken from `emails[primary].value`. In that mode, `emails` must be sent on create and on any update that changes the email.

### Optional user metadata

These attributes are stored and saved for reporting purposes only. We store them when they're sent via SCIM endpoints, and we return them as part of user CSV downloads from the Enterprise Admin Panel.

| Airtable Field | SCIM Attribute                                      | Required |
| -------------- | --------------------------------------------------- | -------- |
| External ID    | `externalId` (ID in the identity provider's system) | False    |
| Title          | `title`                                             | False    |

[Enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3) fields, which are nested inside an object property with the key `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`:

| Airtable Field       | SCIM Attribute        | Required |
| -------------------- | --------------------- | -------- |
| Cost center          | `costCenter`          | False    |
| Department           | `department`          | False    |
| Division             | `division`            | False    |
| Organization         | `organization`        | False    |
| Manager display name | `manager.displayName` | False    |
| Manager              | `manager.value`       | False    |

### Airtable SSO extension

Airtable defines an additional optional extension for routing user provisioning through a particular SSO identity provider when an enterprise has multiple identity providers configured. The fields are nested inside an object property with the key `urn:airtable:params:scim:schemas:extension:sso:2.0:User`:

| Airtable Field         | SCIM Attribute | Required |
| ---------------------- | -------------- | -------- |
| Email domain (for SSO) | `emailDomain`  | False    |

There are two cases where the extension is required or recommended:

1. **Multi-IdP enterprises.** When the enterprise has multiple SSO identity providers configured and the IdP bound to the user's primary email domain does not have `emailAttribute` set, send the extension to route provisioning through an IdP that does. The `emailDomain` value must be a verified domain on the enterprise, and that domain must own an identity provider with `emailAttribute` configured.

2. **Off-domain provisioning.** When the user's primary email is on a domain that is _not_ verified by the enterprise (for example, a franchise or partner email), the extension is **required**. Without it, the request is rejected with `400 — emailDomain extension required for off-domain provisioning`. The targeted IdP must have `emailAttribute` configured. Off-domain users provisioned this way are _not_ auto-verified — they receive a verification email and cannot sign in via SSO until they click the link.

When the extension is omitted and the user's primary email is on a verified domain, Airtable resolves the identity provider from the user's primary email domain (the legacy behavior).

**Validation errors.** Requests that send the extension with an invalid `emailDomain` fail with a `400`. The four reasons are:

-   `missingExtension` — the request provisions an off-domain user without sending the extension.
-   `domainNotVerified` — the `emailDomain` value is not a verified domain on the enterprise.
-   `idpNotFound` — the verified domain does not own (or inherit) an SSO identity provider.
-   `idpMissingEmailAttribute` — the resolved identity provider does not have `emailAttribute` configured.

On responses, Airtable echoes the extension on every SCIM user resource that is bound to an `emailAttribute`-enabled identity provider. The echoed `emailDomain` is server-derived from the user's stored IdP linkage; values sent by the client are not persisted.

Example request body:

```json
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:airtable:params:scim:schemas:extension:sso:2.0:User"
    ],
    "userName": "alice@partner.example.com",
    "name": {"givenName": "Alice", "familyName": "Example"},
    "emails": [{"value": "alice@example.com", "primary": true, "type": "work"}],
    "urn:airtable:params:scim:schemas:extension:sso:2.0:User": {
        "emailDomain": "example.com"
    }
}
```

## SCIM Group Objects

| Airtable Field     | SCIM Attribute    | Required |
| ------------------ | ----------------- | -------- |
| `id`, `groupId`    | `id`              | True     |
| `name`             | `displayName`     | True     |
| `members[].userId` | `members[].value` | True     |