> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin API

## Create Space

You can create a space in your organization programmatically,

```php theme={null}
mutation createSpace(
  $accountOrganizationId: ID!
  $name: String!
  $private: Boolean!

) {
  createSpace(
    input: {
      accountOrganizationId: $accountOrganizationId
      name: $name
      private: $private
    }
  ) {
    space {
      name
      id
    }
  }
}
```

**variables**

```json theme={null}
{
  "accountOrganizationId": "your_org_id",
  "name": "space_name",
  "private": true
}
```

## Query for Users in an Organization

```javascript theme={null}
query getUserIDs{
  node(id:"organization_id"){
    ... on AccountOrganization {
      accountOrganizationUsers{
        edges{
          node{
            user{
              email
              name
              id
            }
          }
        }
      }
    }
  }
}
```

## Delete Users from Space

```javascript theme={null}
mutation removeMemberFromSpace{
  removeSpaceMember(input:
  {
    spaceId:"space_id" #desired space to delete user from 
    userId: "user_id" #returned from the query for users in an org
  })
  {
    clientMutationId
  }
}
```

## Add Users to Space

```python theme={null}
mutation addMembertoSpace{
  assignSpaceMembership(input:
  {
    spaceMemberships:[
      {
        userId: "user_id" 
        spaceId: "space_id" #desired space to add user
        role: member #admin, member, readOnly
      }
    ]
  }){
    spaceMemberships{
      id
      role
    }
  }
}
```

***

## SAML Configuration

Manage SAML IdP configurations via GraphQL. There are three distinct workflows:

1. **Migration from File Config** - Reading existing file-based config and creating a DB entry
2. **Fresh Creation** - Creating a new SAML config from scratch
3. **Updating Existing Config** - Modifying an existing DB-managed config

### Prerequisites: Data Gathering Queries

Before creating or updating SAML configs, gather supporting data: organizations, spaces (mapped to orgs), and available roles.

#### List All SAML Configurations

Use this to find existing configs. Check `isManagedByFile` to determine which workflow to use.

```graphql theme={null}
query SAMLConfigsQuery {
  account {
    id
    allSamlIdPs(first: 50, includeDeleted: true) {
      edges {
        node {
          id
          emailDomainsList {
            id
            domain
            validated
          }
          accountId
          metadataUrl
          metadataXml
          defaultOrgId
          defaultOrgRoleId
          defaultSpaceId
          defaultSpaceRoleId
          syncUserRoles
          signAuthn
          roleMappings {
            id
            attributesMap
            isAccountAdmin
            orgRole {
              orgId
              roleId
            }
            spaceRolesMap
            spaceRbacRolesMap
          }
          enforceSaml
          allowLoginWithDefaults
          createdAt
          createdByUserId
          updatedAt
          isManagedByFile
        }
      }
    }
  }
}
```

<Note>
  `isManagedByFile: true` indicates a file-based config that is read-only through the API. Use Workflow 1 to migrate it to a DB-managed config.
</Note>

#### Query Organizations, Spaces, and Roles

Fetches the org→space mappings and available RBAC roles needed for role mapping configuration.

```graphql theme={null}
query OrganizationsSpacesQuery(
  $orgCount: Int = 100
  $spaceCount: Int = 100
  $roleCount: Int = 100
) {
  account {
    id
    organizations(first: $orgCount) {
      edges {
        node {
          id
          name
          spaces(first: $spaceCount) {
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
    roles(first: $roleCount) {
      edges {
        node {
          id
          name
          description
          isPredefined
          createdAt
          updatedAt
          permissions {
            name
            description
          }
        }
      }
    }
  }
}
```

<Info>
  The `roles` query returns custom RBAC roles. `isPredefined: true` indicates Arize-managed roles that cannot be edited or deleted.
</Info>

**Example Response:**

```json theme={null}
{
  "data": {
    "account": {
      "id": "QWNjb3VudDoxMjM=",
      "organizations": {
        "edges": [
          {
            "node": {
              "id": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
              "name": "Engineering",
              "spaces": {
                "edges": [
                  { "node": { "id": "U3BhY2U6NDU2", "name": "ML Production" } },
                  { "node": { "id": "U3BhY2U6Nzg5", "name": "ML Staging" } }
                ]
              }
            }
          }
        ]
      },
      "roles": {
        "edges": [
          { 
            "node": { 
              "id": "Um9sZToxMjM=", 
              "name": "Admin", 
              "description": "Full access",
              "isPredefined": true,
              "createdAt": "2024-01-01T00:00:00Z",
              "updatedAt": "2024-01-01T00:00:00Z",
              "permissions": [
                { "name": "space.manage", "description": "Manage space settings" }
              ]
            } 
          },
          { 
            "node": { 
              "id": "Um9sZTo0NTY=", 
              "name": "Viewer", 
              "description": "Read-only",
              "isPredefined": false,
              "createdAt": "2024-06-15T10:30:00Z",
              "updatedAt": "2024-06-15T10:30:00Z",
              "permissions": [
                { "name": "space.view", "description": "View space content" }
              ]
            } 
          }
        ]
      }
    }
  }
}
```

### Workflow 1: Migrate File Config to Database

When `isManagedByFile: true` on an existing SAML config, you must **create** a new DB-managed config (not update). The file-based config is read-only through the API.

<Steps>
  <Step title="Read Existing Config Values">
    Use `SAMLConfigsQuery` above to read the file-managed config's values.
  </Step>

  <Step title="Map to CreateSAMLIdPInput">
    Transform the queried config data into a create input:

    ```typescript theme={null}
    const fileConfig = queryResult.account.allSamlIdPs.edges[0].node;

    const createInput = {
      metadataUrl: fileConfig.metadataUrl,      // OR metadataXml, not both
      metadataXml: fileConfig.metadataXml,
      emailDomainsList: fileConfig.emailDomainsList.map(d => ({
        domain: d.domain,
        validated: d.validated
      })),
      defaultOrgId: fileConfig.defaultOrgId,
      defaultOrgRoleId: fileConfig.defaultOrgRoleId,
      defaultSpaceId: fileConfig.defaultSpaceId,
      defaultSpaceRoleId: fileConfig.defaultSpaceRoleId,
      syncUserRoles: fileConfig.syncUserRoles,
      signAuthn: fileConfig.signAuthn,
      enforceSaml: fileConfig.enforceSaml,
      allowLoginWithDefaults: fileConfig.allowLoginWithDefaults,
      roleMappings: {
        mappingsList: fileConfig.roleMappings?.map(rm => ({
          attributesMap: rm.attributesMap,
          isAccountAdmin: rm.isAccountAdmin,
          orgRole: rm.orgRole ? {
            orgId: rm.orgRole.orgId,
            roleId: rm.orgRole.roleId
          } : null,
          spaceRolesMap: rm.spaceRolesMap,
          spaceRbacRolesMap: rm.spaceRbacRolesMap
        }))
      }
    };
    ```
  </Step>

  <Step title="Execute Create Mutation">
    See "Create SAML Configuration" below.
  </Step>
</Steps>

### Workflow 2: Create New Config (Fresh)

<Steps>
  <Step title="Gather Support Data">
    Run `OrganizationsSpacesQuery` to get available orgs, spaces, and roles.
  </Step>

  <Step title="Execute Create Mutation">
    See "Create SAML Configuration" below.
  </Step>
</Steps>

### Workflow 3: Update Existing DB Config

<Warning>
  Updates are **full replacements** - you must send the complete configuration. Omitting fields may reset them to defaults.
</Warning>

<Steps>
  <Step title="List Configs to Get Target ID">
    Use `SAMLConfigsQuery` to find the config. Ensure `isManagedByFile: false`.
  </Step>

  <Step title="Gather Support Data">
    Run `OrganizationsSpacesQuery` for org→space mappings and role IDs.
  </Step>

  <Step title="Execute Update Mutation">
    See "Update SAML Configuration" below.
  </Step>
</Steps>

### Create SAML Configuration

```graphql theme={null}
mutation CreateSAMLIdPMutation($input: CreateSAMLIdPInput!) {
  createSAMLIdP(input: $input) {
    idp {
      id
      emailDomainsList {
        id
        domain
        validated
      }
      accountId
      metadataUrl
      metadataXml
      defaultOrgId
      defaultOrgRoleId
      defaultSpaceId
      defaultSpaceRoleId
      syncUserRoles
      signAuthn
      roleMappings {
        id
        attributesMap
        isAccountAdmin
        orgRole {
          orgId
          roleId
        }
        spaceRolesMap
        spaceRbacRolesMap
      }
      enforceSaml
      allowLoginWithDefaults
      createdAt
      createdByUserId
      updatedAt
    }
    error
  }
}
```

<Tabs>
  <Tab title="Minimal Example">
    Use `allowLoginWithDefaults: true` to allow users to log in without matching role mappings:

    ```json theme={null}
    {
      "input": {
        "emailDomainsList": [
          { "domain": "newcompany.com", "validated": false }
        ],
        "metadataUrl": "https://idp.newcompany.com/saml2/metadata",
        "allowLoginWithDefaults": true,
        "defaultOrgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
        "defaultOrgRoleId": "member",
        "defaultSpaceId": "U3BhY2U6NDU2",
        "defaultSpaceRoleId": "member"
      }
    }
    ```
  </Tab>

  <Tab title="Full Example with Role Mappings">
    ```json theme={null}
    {
      "input": {
        "emailDomainsList": [
          { "domain": "enterprise.com", "validated": false }
        ],
        "metadataXml": "<?xml version=\"1.0\"?>...<EntityDescriptor>...</EntityDescriptor>",
        "enforceSaml": true,
        "allowLoginWithDefaults": false,
        "syncUserRoles": true,
        "signAuthn": true,
        "defaultOrgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
        "defaultOrgRoleId": "member",
        "defaultSpaceId": "U3BhY2U6NDU2",
        "defaultSpaceRoleId": "readOnly",
        "roleMappings": {
          "mappingsList": [
            {
              "attributesMap": [["memberOf", "cn=admins,ou=groups,dc=enterprise,dc=com"]],
              "isAccountAdmin": true,
              "orgRole": null,
              "spaceRolesMap": [],
              "spaceRbacRolesMap": []
            },
            {
              "attributesMap": [["department", "data-science"]],
              "isAccountAdmin": false,
              "orgRole": {
                "orgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
                "roleId": "admin"
              },
              "spaceRolesMap": [
                ["U3BhY2U6NDU2", "admin"],
                ["U3BhY2U6Nzg5", "member"]
              ],
              "spaceRbacRolesMap": []
            },
            {
              "attributesMap": [["department", "ml-ops"]],
              "isAccountAdmin": false,
              "orgRole": {
                "orgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
                "roleId": "member"
              },
              "spaceRolesMap": [],
              "spaceRbacRolesMap": [
                ["U3BhY2U6NDU2", "Um9sZToxMjM="],
                ["U3BhY2U6Nzg5", "Um9sZTo0NTY="]
              ]
            }
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Update SAML Configuration

```graphql theme={null}
mutation UpdateSAMLIdPMutation($input: UpdateSAMLIdPInput!) {
  updateSAMLIdP(input: $input) {
    idp {
      id
      emailDomainsList {
        id
        domain
        validated
      }
      accountId
      metadataUrl
      metadataXml
      defaultOrgId
      defaultOrgRoleId
      defaultSpaceId
      defaultSpaceRoleId
      syncUserRoles
      signAuthn
      roleMappings {
        id
        attributesMap
        isAccountAdmin
        orgRole {
          orgId
          roleId
        }
        spaceRolesMap
        spaceRbacRolesMap
      }
      enforceSaml
      allowLoginWithDefaults
      createdAt
      createdByUserId
      updatedAt
    }
    error
  }
}
```

**Variables (Full Replacement):**

```json theme={null}
{
  "input": {
    "id": "U0FNTElkUDoxMjM0NTY=",
    "emailDomainsList": [
      { "domain": "company.com", "validated": true },
      { "domain": "subsidiary.com", "validated": false }
    ],
    "metadataUrl": "https://idp.company.com/saml/metadata/v2",
    "enforceSaml": true,
    "allowLoginWithDefaults": false,
    "syncUserRoles": true,
    "signAuthn": true,
    "defaultOrgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
    "defaultOrgRoleId": "member",
    "defaultSpaceId": "U3BhY2U6NDU2",
    "defaultSpaceRoleId": "member",
    "roleMappings": {
      "mappingsList": [
        {
          "attributesMap": [["role", "platform-admin"]],
          "isAccountAdmin": true,
          "orgRole": null,
          "spaceRolesMap": [],
          "spaceRbacRolesMap": []
        },
        {
          "attributesMap": [["team", "ml-eng"]],
          "isAccountAdmin": false,
          "orgRole": {
            "orgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
            "roleId": "admin"
          },
          "spaceRbacRolesMap": [
            ["U3BhY2U6NDU2", "Um9sZToxMjM="]
          ],
          "spaceRolesMap": []
        }
      ]
    }
  }
}
```

#### Clear All Role Mappings

To remove all role mappings, you must enable `allowLoginWithDefaults`:

```json theme={null}
{
  "input": {
    "id": "U0FNTElkUDoxMjM0NTY=",
    "emailDomainsList": [{ "domain": "company.com", "validated": true }],
    "enforceSaml": false,
    "allowLoginWithDefaults": true,
    "defaultOrgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
    "defaultOrgRoleId": "member",
    "defaultSpaceId": "U3BhY2U6NDU2",
    "defaultSpaceRoleId": "member",
    "roleMappings": {
      "mappingsList": []
    }
  }
}
```

### Delete SAML Configuration

```graphql theme={null}
mutation DeleteSAMLIdPMutation($input: DeleteSAMLIdPInput!) {
  deleteSAMLIdP(input: $input) {
    error
  }
}
```

**Variables:**

```json theme={null}
{
  "input": {
    "id": "U0FNTElkUDoxMjM0NTY="
  }
}
```

### Input Type Reference

#### CreateSAMLIdPInput

| Field                    | Type                   | Required | Description                                                 |
| ------------------------ | ---------------------- | -------- | ----------------------------------------------------------- |
| `emailDomainsList`       | `[EmailDomainInput!]!` | Yes      | At least one email domain                                   |
| `metadataUrl`            | `String`               | No\*     | URL to IdP metadata (mutually exclusive with `metadataXml`) |
| `metadataXml`            | `String`               | No\*     | Raw XML metadata (mutually exclusive with `metadataUrl`)    |
| `defaultOrgId`           | `ID`                   | No       | Default organization for new users                          |
| `defaultOrgRoleId`       | `ID`                   | No       | Default org role: `"admin"`, `"member"`, or custom role ID  |
| `defaultSpaceId`         | `ID`                   | No       | Default space for new users                                 |
| `defaultSpaceRoleId`     | `ID`                   | No       | Default space role                                          |
| `syncUserRoles`          | `Boolean`              | No       | Sync roles on every login (default: false)                  |
| `signAuthn`              | `Boolean`              | No       | Sign SAML AuthN requests (default: false)                   |
| `enforceSaml`            | `Boolean`              | No       | Only allow SAML login (default: false)                      |
| `allowLoginWithDefaults` | `Boolean`              | No       | Allow login without role mapping match                      |
| `roleMappings`           | `RoleMappingsInput`    | No       | SAML attribute → role mappings                              |

<Info>
  One of `metadataUrl` or `metadataXml` should be provided.
</Info>

#### UpdateSAMLIdPInput

Same as `CreateSAMLIdPInput` plus:

| Field              | Type                 | Required | Description                               |
| ------------------ | -------------------- | -------- | ----------------------------------------- |
| `id`               | `ID!`                | Yes      | Unique identifier of the config to update |
| `emailDomainsList` | `[EmailDomainInput]` | No       | Optional on update (null = keep existing) |

#### EmailDomainInput

| Field       | Type      | Required | Description                               |
| ----------- | --------- | -------- | ----------------------------------------- |
| `domain`    | `String!` | Yes      | Email domain (e.g., `"company.com"`)      |
| `id`        | `ID`      | No       | Optional ID for existing domains          |
| `validated` | `Boolean` | No       | Domain validation status (Arize-internal) |

#### RoleMappingsInput

| Field          | Type                 | Required | Description                |
| -------------- | -------------------- | -------- | -------------------------- |
| `mappingsList` | `[RoleMappingInput]` | No       | List of role mapping rules |

#### RoleMappingInput

| Field               | Type           | Required | Description                                               |
| ------------------- | -------------- | -------- | --------------------------------------------------------- |
| `id`                | `ID`           | No       | Optional ID for existing mappings                         |
| `attributesMap`     | `[[String]]`   | No       | SAML attribute key-value pairs: `[["key", "value"], ...]` |
| `isAccountAdmin`    | `Boolean`      | No       | Grant account admin privileges                            |
| `orgRole`           | `OrgRoleInput` | No       | Organization role assignment                              |
| `spaceRolesMap`     | `[[String]]`   | No       | Legacy space roles: `[["spaceId", "role"], ...]`          |
| `spaceRbacRolesMap` | `[[String!]!]` | No       | RBAC space roles: `[["spaceId", "roleGlobalId"], ...]`    |

<Warning>
  `spaceRolesMap` and `spaceRbacRolesMap` are mutually exclusive per mapping.
</Warning>

#### OrgRoleInput

| Field    | Type | Required | Description                                    |
| -------- | ---- | -------- | ---------------------------------------------- |
| `orgId`  | `ID` | No       | Unique organization identifier                 |
| `roleId` | `ID` | No       | Role: `"admin"`, `"member"`, or custom role ID |

### Role ID Values

#### Organization Roles (orgRole.roleId)

Built-in roles for organization membership:

| Value        | Description                                             |
| ------------ | ------------------------------------------------------- |
| `"admin"`    | Organization administrator - full org management access |
| `"member"`   | Organization member - standard access                   |
| `"readOnly"` | Read-only organization access                           |

<Warning>
  The `annotator` role is **not available** for organization roles in SAML role mappings. Annotators must be configured at the space level using `spaceRolesMap`.
</Warning>

#### Space Roles (spaceRolesMap values)

Built-in roles for space membership (legacy, use `spaceRbacRolesMap` for custom roles):

| Value         | Description                                               |
| ------------- | --------------------------------------------------------- |
| `"admin"`     | Space administrator - full space management               |
| `"member"`    | Space member - read/write access                          |
| `"readOnly"`  | Read-only space access                                    |
| `"annotator"` | Annotator role - can only access assigned labeling queues |

<Warning>
  Note the camelCase: `"readOnly"` not `"readonly"`. These values are case-sensitive.
</Warning>

#### RBAC Roles (spaceRbacRolesMap)

For custom RBAC roles, use the unique IDs from the `roles` query:

```graphql theme={null}
query GetRoles {
  account {
    roles(first: 100) {
      edges {
        node {
          id           # Use this ID in spaceRbacRolesMap
          name
          description
          isPredefined # true = Arize-managed, cannot be modified
        }
      }
    }
  }
}
```

Example mapping: `[["U3BhY2U6NDU2", "Um9sZToxMjM="]]` maps space ID to RBAC role ID.

### Error Handling

All mutations return an `error` field. Check this before assuming success:

```typescript theme={null}
if (result.createSAMLIdP?.error) {
  console.error("SAML config creation failed:", result.createSAMLIdP.error);
  return;
}
// Success - use result.createSAMLIdP.idp
```

**Common errors:**

* `"Email domain already in use"` - Domain registered to another config
* `"Role mappings required when allowLoginWithDefaults is false"` - Need at least one mapping
* `"Cannot update file-managed SAML configuration"` - Config has `isManagedByFile: true`
* `"Invalid metadata URL/XML"` - Metadata parsing failed

### Workflow Decision Tree

```
Does SAML config exist?
├── No → Workflow 2: Create New Config
└── Yes
    └── Is isManagedByFile true?
        ├── Yes → Workflow 1: Migrate File to DB (Create new)
        └── No → Workflow 3: Update Existing Config
```