Skip to main content

​
Create Space

You can create a space in your organization programmatically, 
mutation createSpace(
  $accountOrganizationId: ID!
  $name: String!
  $private: Boolean!

) {
  createSpace(
    input: {
      accountOrganizationId: $accountOrganizationId
      name: $name
      private: $private
    }
  ) {
    space {
      name
      id
    }
  }
}
variables 
{
  "accountOrganizationId": "your_org_id",
  "name": "space_name",
  "private": true
}

​
Query for Users in an Organization

query getUserIDs{
  node(id:"organization_id"){
    ... on AccountOrganization {
      accountOrganizationUsers{
        edges{
          node{
            user{
              email
              name
              id
            }
          }
        }
      }
    }
  }
}

​
Delete Users from Space

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

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. 
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
        }
      }
    }
  }
}
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.

​
Query Organizations, Spaces, and Roles

Fetches the org→space mappings and available RBAC roles needed for role mapping configuration. 
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
          }
        }
      }
    }
  }
}
The roles query returns custom RBAC roles. isPredefined: true indicates Arize-managed roles that cannot be edited or deleted.
Example Response: 
{
  "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.
1

Read Existing Config Values

Use SAMLConfigsQuery above to read the file-managed config’s values.
2

Map to CreateSAMLIdPInput

Transform the queried config data into a create input:
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
    }))
  }
};
3

Execute Create Mutation

See “Create SAML Configuration” below.

​
Workflow 2: Create New Config (Fresh)

1

Gather Support Data

Run OrganizationsSpacesQuery to get available orgs, spaces, and roles.
2

Execute Create Mutation

See “Create SAML Configuration” below.

​
Workflow 3: Update Existing DB Config

Updates are full replacements - you must send the complete configuration. Omitting fields may reset them to defaults.
1

List Configs to Get Target ID

Use SAMLConfigsQuery to find the config. Ensure isManagedByFile: false.
2

Gather Support Data

Run OrganizationsSpacesQuery for org→space mappings and role IDs.
3

Execute Update Mutation

See “Update SAML Configuration” below.

​
Create SAML Configuration

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
  }
}
Use allowLoginWithDefaults: true to allow users to log in without matching role mappings:
{
  "input": {
    "emailDomainsList": [
      { "domain": "newcompany.com", "validated": false }
    ],
    "metadataUrl": "https://idp.newcompany.com/saml2/metadata",
    "allowLoginWithDefaults": true,
    "defaultOrgId": "QWNjb3VudE9yZ2FuaXphdGlvbjoxMjM=",
    "defaultOrgRoleId": "member",
    "defaultSpaceId": "U3BhY2U6NDU2",
    "defaultSpaceRoleId": "member"
  }
}

​
Update SAML Configuration

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): 
{
  "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: 
{
  "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

mutation DeleteSAMLIdPMutation($input: DeleteSAMLIdPInput!) {
  deleteSAMLIdP(input: $input) {
    error
  }
}
Variables: 
{
  "input": {
    "id": "U0FNTElkUDoxMjM0NTY="
  }
}

​
Input Type Reference

​
CreateSAMLIdPInput

FieldTypeRequiredDescription
emailDomainsList[EmailDomainInput!]!YesAt least one email domain
metadataUrlStringNo*URL to IdP metadata (mutually exclusive with metadataXml)
metadataXmlStringNo*Raw XML metadata (mutually exclusive with metadataUrl)
defaultOrgIdIDNoDefault organization for new users
defaultOrgRoleIdIDNoDefault org role: "admin", "member", or custom role ID
defaultSpaceIdIDNoDefault space for new users
defaultSpaceRoleIdIDNoDefault space role
syncUserRolesBooleanNoSync roles on every login (default: false)
signAuthnBooleanNoSign SAML AuthN requests (default: false)
enforceSamlBooleanNoOnly allow SAML login (default: false)
allowLoginWithDefaultsBooleanNoAllow login without role mapping match
roleMappingsRoleMappingsInputNoSAML attribute → role mappings
One of metadataUrl or metadataXml should be provided.

​
UpdateSAMLIdPInput

Same as CreateSAMLIdPInput plus:
FieldTypeRequiredDescription
idID!YesRelay global ID of the config to update
emailDomainsList[EmailDomainInput]NoOptional on update (null = keep existing)

​
EmailDomainInput

FieldTypeRequiredDescription
domainString!YesEmail domain (e.g., "company.com")
idIDNoOptional ID for existing domains
validatedBooleanNoDomain validation status (Arize-internal)

​
RoleMappingsInput

FieldTypeRequiredDescription
mappingsList[RoleMappingInput]NoList of role mapping rules

​
RoleMappingInput

FieldTypeRequiredDescription
idIDNoOptional ID for existing mappings
attributesMap[[String]]NoSAML attribute key-value pairs: [["key", "value"], ...]
isAccountAdminBooleanNoGrant account admin privileges
orgRoleOrgRoleInputNoOrganization role assignment
spaceRolesMap[[String]]NoLegacy space roles: [["spaceId", "role"], ...]
spaceRbacRolesMap[[String!]!]NoRBAC space roles: [["spaceId", "roleGlobalId"], ...]
spaceRolesMap and spaceRbacRolesMap are mutually exclusive per mapping.

​
OrgRoleInput

FieldTypeRequiredDescription
orgIdIDNoOrganization Relay global ID
roleIdIDNoRole: "admin", "member", or custom role ID

​
Role ID Values

​
Organization Roles (orgRole.roleId)

Built-in roles for organization membership:
ValueDescription
"admin"Organization administrator - full org management access
"member"Organization member - standard access
"readOnly"Read-only organization access
The annotator role is not available for organization roles in SAML role mappings. Annotators must be configured at the space level using spaceRolesMap.

​
Space Roles (spaceRolesMap values)

Built-in roles for space membership (legacy, use spaceRbacRolesMap for custom roles):
ValueDescription
"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
Note the camelCase: "readOnly" not "readonly". These values are case-sensitive.

​
RBAC Roles (spaceRbacRolesMap)

For custom RBAC roles, use Relay global IDs from the roles query: 
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: 
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