> For the complete documentation index, see [llms.txt](https://docs.meterian.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meterian.io/the-meterian-webapp/advanced-functionalities/sso-configuration/scim-2.0.md).

# SCIM 2.0

Meterian exposes a [SCIM 2.0](https://datatracker.ietf.org/doc/html/rfc7644) REST API so that your identity provider (IdP) can provision and de-provision users and teams in your Meterian account automatically. It is the companion to [SSO configuration](/the-meterian-webapp/advanced-functionalities/sso-configuration.md): SSO controls *how* users log in, while SCIM keeps the list of users and their team membership in sync.

{% hint style="warning" %}
**Note:** The SCIM API is bound to its own feature flag, which must be enabled on your account before it can be used. Contact Meterian sales to request it.
{% endhint %}

## Base URL

All endpoints are served under:

```
https://www.meterian.io/api/v1/scim
```

Requests and responses use the `application/scim+json` content type.

## API explorer

An interactive UI is available so you can browse the endpoints and try requests from the browser: 

<https://www.meterian.io/scim/documentation/api-docs>

The raw OpenAPI specification is served at <https://www.meterian.io/scim/documentation/api-docs>

## Authentication

The API uses **HTTP Basic** authentication. The credentials are your **account UUID** as the username and a **Meterian API token** as the password, joined with a colon and Base64-encoded:

```
Authorization: Basic base64(accountUUID:meterianApiToken)
```

You can find your **account UUID** in the dashboard under the **Details** tab, in the **Account** section: it is shown in the read-only "UUID" field, with a copy-to-clipboard button next to it.

<figure><img src="/files/h6TEgP93ePRGbQrTd2q6" alt=""><figcaption></figcaption></figure>

Every request must carry this header, except for the unauthenticated discovery endpoints (`/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`). If the header is missing or invalid the API responds with `401 Unauthorized`.

## Endpoints

### Users

| Method   | Path          | Purpose                                                       |
| -------- | ------------- | ------------------------------------------------------------- |
| `GET`    | `/Users`      | List users (supports `startIndex` and `count` for pagination) |
| `POST`   | `/Users`      | Create a user                                                 |
| `GET`    | `/Users/{id}` | Fetch a single user by UUID                                   |
| `PUT`    | `/Users/{id}` | Replace a user                                                |
| `PATCH`  | `/Users/{id}` | Partially update a user                                       |
| `DELETE` | `/Users/{id}` | Remove a user                                                 |

### Groups (teams)

Meterian **teams** are exposed as SCIM **Groups**.

| Method   | Path           | Purpose                                        |
| -------- | -------------- | ---------------------------------------------- |
| `GET`    | `/Groups`      | List teams (supports `startIndex` and `count`) |
| `POST`   | `/Groups`      | Create a team                                  |
| `GET`    | `/Groups/{id}` | Fetch a single team by UUID or name            |
| `PUT`    | `/Groups/{id}` | Replace a team                                 |
| `PATCH`  | `/Groups/{id}` | Add, update or remove members                  |
| `DELETE` | `/Groups/{id}` | Delete a team                                  |

### Discovery (no authentication)

| Method | Path                     | Purpose                                                  |
| ------ | ------------------------ | -------------------------------------------------------- |
| `GET`  | `/ServiceProviderConfig` | Capabilities advertised by the server                    |
| `GET`  | `/ResourceTypes`         | Supported resource types                                 |
| `GET`  | `/Schemas`               | Schema definitions (`/Schemas/Users`, `/Schemas/Groups`) |

{% hint style="info" %}
Pagination only. The server advertises `patch: true` but `filter: false`, `sort: false` and `bulk: false` — listing endpoints support `startIndex`/`count` paging but not filtering or sorting.
{% endhint %}

## Schemas

The API uses the standard SCIM 2.0 schemas plus a Meterian extension that adds a **role** to group members:

* User — `urn:ietf:params:scim:schemas:core:2.0:User`
* Group — `urn:ietf:params:scim:schemas:core:2.0:Group`
* Group member role (Meterian extension) — adds a `role` attribute to each entry in a group's `members` array.

Valid role values are **Administrator**, **Collaborator** and **Viewer**. When a role is not supplied, the user defaults to **Viewer**.

A user's `userName` must be a valid **email address**, and the email cannot be changed once the user has been created.

## Examples

**List users**

```bash
curl -s "https://www.meterian.io/api/v1/scim/Users?startIndex=1&count=100" \
  -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)"
```

**Create a user**

```bash
curl -s -X POST "https://www.meterian.io/api/v1/scim/Users" \
  -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "example@acme.com",
    "name": { "givenName": "Example", "familyName": "User" },
    "roles": [{ "value": "Collaborator" }]
  }'
```

**Add a member to a team**

```bash
curl -s -X PATCH "https://www.meterian.io/api/v1/scim/Groups/{teamId}" \
  -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
      "op": "add",
      "path": "members",
      "value": { "display": "Example User", "value": "example@acme.com", "type": "User", "role": "Collaborator" }
    }]
  }'
```

The `Operations` array also accepts `replace` (to change a member's role) and `remove` (to take a member out of the team).

## Errors

Errors are returned as SCIM error messages with the matching HTTP status code:

```json
{
  "status": 400,
  "message": "The userName field is required to be an email address.",
  "scimType": "invalidValue"
}
```

Common cases:

| Status | Meaning                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid or missing field (e.g. `userName` is not an email, or an attempt to change an immutable email) |
| `401`  | Missing or invalid `Authorization` header                                                              |
| `500`  | Unexpected server error                                                                                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meterian.io/the-meterian-webapp/advanced-functionalities/sso-configuration/scim-2.0.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.