HTTP API Reference

User attributes API reference

Manage user attributes and attribute definitions to enable parameterized role-based access control

User Attribute

This is a paid feature

This feature is available on certain Enterprise plans. Talk to sales to learn more.

An attribute is a named piece of identity data associated with a user within an organization, such as location="torrevieja" or department="front_desk".

Attributes can come from two sources: SAML, where they are automatically captured from assertions during SSO authentication, and Sanity, where they are set by administrators through the API or Manage interface.

Attributes can be referenced in GROQ filters within role definitions using the user::attributes() function, enabling parameterized access control that adapts dynamically to each user.

Base API server URL

https://api.sanity.io

Attribute Definitions

Manage organization-level attribute definitions that define the schema and type of user attributes.

Attribute definitions specify the attribute key (name) and type (string, integer, number, boolean, with optional array variants). Definitions are grouped by key and show all sources (sources) where that key is defined:

  • SAML definitions are automatically created when users authenticate via SSO providers like Okta or Azure AD
  • Sanity definitions are created through this API by organization administrators

When an attribute key exists in both SAML and Sanity sources, the sources array will contain both ['saml', 'sanity'].

Important Restrictions:

  • You cannot create SAML definitions through the API - they are only created automatically during SAML sync.
  • You cannot create Sanity definitions when a SAML definition already exists for that key. Sanity definitions for SAML attributes are auto-created when the first Sanity value is set.
  • You cannot delete definitions (via API) if they have SAML sources or are currently in use by any users.

Automatic Cleanup:

  • SAML-only definitions are auto-deleted during SAML sync when no longer provided by SSO and no users have values.
  • Sanity definitions are auto-deleted when deleting user values IF a SAML definition exists for the same key AND no users have Sanity values.
  • Sanity-only definitions are never auto-deleted (must be manually deleted when not in use).

These definitions serve as the foundation for creating roles with parameterized filters, enabling dynamic access control based on user attributes such as location, department, or region.

List Attribute Definitions

get/vX/organizations/{organizationId}/attribute-definitions

Retrieve a paginated list of attribute definitions for an organization.

Definitions are grouped by key and show all sources where that key is defined.

Permissions

Requires sanity.organization.manage permission.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123

Query parameters

  • cursorstring

    Cursor for pagination

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

Successfully retrieved attribute definitions

  • definitionsarrayrequired

    List of attribute definitions grouped by key

    Show child attributes
    items
    • keystringrequired

      Textual name of the attribute

      Example:year_started
    • typestringrequired

      Type of the attribute

    • sourcesarrayrequired

      All sources where this attribute key is defined. Can contain 'saml', 'sanity', or both. When both sources exist, it indicates the same attribute key is defined in both SAML and API-managed contexts.

      Example
      ["saml","sanity"]
      Show child attributes
      items
      • string

        Source of the attribute:

        • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
        • sanity: Created and managed through this API by organization administrators
        enum:"saml", "sanity"
    • createdAtstring (date-time)required

      Timestamp when the definition was first created (uses earliest created definition when multiple sources exist)

      Example:2026-01-08T12:00:00Z
    • alreadyExistsboolean

      Only present in POST responses. When true, indicates the definition already existed and was returned instead of being created.

      Example:true
  • nextCursorstring | null

    Cursor for the next page of results (the last key from this page)

  • hasMorebooleanrequired

    Indicates if there are more results available

Create Attribute Definition

post/vX/organizations/{organizationId}/attribute-definitions

Create a new Sanity (API-managed) attribute definition for an organization.

This endpoint only creates Sanity definitions. SAML definitions are automatically created during SSO authentication and cannot be created through this API.

Important restrictions:

  • Cannot create Sanity definition when SAML definition exists: If a SAML definition already exists for the key, this endpoint returns 403 Forbidden. Sanity definitions for SAML attributes are automatically created when you set the first Sanity value for that attribute.
  • Existing Sanity definitions: If a Sanity definition with the same key already exists, it returns the existing definition with alreadyExists: true.
  • Type validation: If a definition exists with a different type, returns 409 Conflict.

Permissions

Requires sanity.organization.manage permission.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123

Request body application/json

  • keystringrequired

    Textual name of the attribute

    Example:year_started
  • typestringrequired

    Type of the attribute

Responses

200

Attribute definition already exists (returned existing definition with alreadyExists flag)

  • keystringrequired

    Textual name of the attribute

    Example:year_started
  • typestringrequired

    Type of the attribute

  • sourcesarrayrequired

    All sources where this attribute key is defined. Can contain 'saml', 'sanity', or both. When both sources exist, it indicates the same attribute key is defined in both SAML and API-managed contexts.

    Example
    ["saml","sanity"]
    Show child attributes
    items
    • string

      Source of the attribute:

      • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
      • sanity: Created and managed through this API by organization administrators
      enum:"saml", "sanity"
  • createdAtstring (date-time)required

    Timestamp when the definition was first created (uses earliest created definition when multiple sources exist)

    Example:2026-01-08T12:00:00Z
  • alreadyExistsboolean

    Only present in POST responses. When true, indicates the definition already existed and was returned instead of being created.

    Example:true

Delete Attribute Definition

delete/vX/organizations/{organizationId}/attribute-definitions/{key}

Delete an attribute definition by key. Important restrictions:

  • Cannot delete if SAML source exists: If the attribute has a SAML definition (sources includes 'saml'), deletion is forbidden (403). This applies even if you want to delete only the API-managed part.
  • Cannot delete if in use: If any user has values for this attribute (API-managed or SAML), deletion fails (409).
  • API-managed only: Only attributes with sources: ['sanity'] can be deleted, and only when no users have values.

Note: API-managed definitions are often automatically cleaned up when you delete user attribute values (if a SAML definition exists for the same key). Use this endpoint only for cleaning up unused API-managed-only definitions.

Permissions

Requires sanity.organization.manage permission.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123
  • keystringrequired

    Textual name of the attribute

    Example:year_started

Responses

204

Attribute definition deleted successfully

User Attributes

Manage user-specific attribute values within an organization.

User attributes contain the actual values assigned to users (e.g., location="UK", department=["hr", "sales"]). Each attribute can originate from different sources:

  • SAML: Automatically set/updated when users authenticate via SSO (not managed through this API)
  • Sanity: Manually set by organization administrators through this API using attribute keys

When reading attributes, you'll see:

  • values: All available values from each source (e.g., {saml: "US", sanity: "UK"})
  • activeSource: Which source is currently in effect (Sanity values always take precedence)
  • activeValue: The actual value being used in access control

When you set a Sanity value for an attribute key that also has a SAML value, the Sanity value becomes active but the SAML value remains visible in the values object. Deleting the Sanity value makes the SAML value active again.

These attributes enable parameterized role-based access control and filtering.

Get My Attributes

get/vX/organizations/{organizationId}/users/me/attributes

Retrieve your own attributes within an organization.

This endpoint returns all attributes for the current authenticated user, including both SAML and Sanity values. Each attribute includes:

  • values: Object showing values from all sources (e.g., {saml: "US", sanity: "UK"})
  • activeSource: Which source is currently in effect ('saml' or 'sanity')
  • activeValue: The actual value being used in access control

When an attribute exists in both SAML and Sanity sources, the values object will contain both, and activeSource will be 'sanity' since Sanity values take precedence.

Permissions

No special permission required - users can always read their own attributes.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123

Query parameters

  • limitintegerdefault: 50

    Maximum number of attributes to return

  • cursorstring

    The last attribute key from the previous page (used for pagination)

Responses

200

Successfully retrieved your attributes

  • sanityUserIdstringrequired

    ID of the user

    Example:user-xyz
  • organizationIdstringrequired

    ID of the organization

    Example:org-123
  • attributesarrayrequired
    Show child attributes
    items
    • typestringrequired

      Type of the attribute

    • keystringrequired

      Textual name of the attribute

      Example:location
    • valuesobjectrequired

      Values from all available sources. Contains 'saml' and/or 'sanity' keys with their respective values. Shows all values regardless of precedence, making it clear which values are being shadowed.

      Example
      {"saml":"US","sanity":"UK"}
      Show child attributes
      • saml

        Value from SAML source (if exists)

        Show child attributes
        • string
      • sanity

        Value from Sanity source (if exists)

        Show child attributes
        • string
    • activeSourcestringrequired

      Source of the attribute:

      • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
      • sanity: Created and managed through this API by organization administrators
    • activeValuerequired

      The value currently in effect, taken from the activeSource. This is the value that will be used in access control evaluations and role filters.

      Example:UK
      Show child attributes
      • string

Get User Attributes

get/vX/organizations/{organizationId}/users/{sanityUserId}/attributes

Retrieve attributes for a user within an organization.

This endpoint returns all attributes for a user, including both SAML and Sanity values. Each attribute includes:

  • values: Object showing values from all sources (e.g., {saml: "US", sanity: "UK"})
  • activeSource: Which source is currently in effect ('saml' or 'sanity')
  • activeValue: The actual value being used in access control

When an attribute exists in both SAML and Sanity sources, the values object will contain both, and activeSource will be 'sanity' since Sanity values take precedence.

Permissions

  • To read your own attributes: No special permission required
  • To read other users' attributes: Requires sanity.organization.manage permission
  • This only applies for organizations you have permissions for.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123
  • sanityUserIdstringrequired

    Unique identifier of the Sanity user

    Example:u1

Query parameters

  • limitintegerdefault: 50

    Maximum number of attributes to return

  • cursorstring

    The last attribute key from the previous page (used for pagination)

Responses

200

Successfully retrieved user attributes

  • sanityUserIdstringrequired

    ID of the user

    Example:user-xyz
  • organizationIdstringrequired

    ID of the organization

    Example:org-123
  • attributesarrayrequired
    Show child attributes
    items
    • typestringrequired

      Type of the attribute

    • keystringrequired

      Textual name of the attribute

      Example:location
    • valuesobjectrequired

      Values from all available sources. Contains 'saml' and/or 'sanity' keys with their respective values. Shows all values regardless of precedence, making it clear which values are being shadowed.

      Example
      {"saml":"US","sanity":"UK"}
      Show child attributes
      • saml

        Value from SAML source (if exists)

        Show child attributes
        • string
      • sanity

        Value from Sanity source (if exists)

        Show child attributes
        • string
    • activeSourcestringrequired

      Source of the attribute:

      • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
      • sanity: Created and managed through this API by organization administrators
    • activeValuerequired

      The value currently in effect, taken from the activeSource. This is the value that will be used in access control evaluations and role filters.

      Example:UK
      Show child attributes
      • string

Update User Attributes

post/vX/organizations/{organizationId}/users/{sanityUserId}/attributes

Set or update attribute values for a user using attribute keys.

When you set a value for an attribute key that also exists in SAML, your Sanity value will take precedence and shadow the SAML value. The SAML value remains in the system and is visible in the values object.

If the attribute key doesn't have a Sanity definition yet, one will be created automatically.

This endpoint returns at most the first 50 attributes after the update, prioritizing attributes with values.

Permissions

Requires sanity.organization.manage permission.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123
  • sanityUserIdstringrequired

    Unique identifier of the Sanity user

    Example:u1

Request body application/json

  • attributesarrayrequired

    Array of attributes to set with their keys and values

    Show child attributes
    items
    • keystringrequired

      Textual name of the attribute (e.g., 'location', 'department')

    • valuerequired

      Value to set for the attribute

      Show child attributes
      • string

Responses

200

Attributes updated successfully

  • sanityUserIdstringrequired

    ID of the user

    Example:user-xyz
  • organizationIdstringrequired

    ID of the organization

    Example:org-123
  • attributesarrayrequired
    Show child attributes
    items
    • typestringrequired

      Type of the attribute

    • keystringrequired

      Textual name of the attribute

      Example:location
    • valuesobjectrequired

      Values from all available sources. Contains 'saml' and/or 'sanity' keys with their respective values. Shows all values regardless of precedence, making it clear which values are being shadowed.

      Example
      {"saml":"US","sanity":"UK"}
      Show child attributes
      • saml

        Value from SAML source (if exists)

        Show child attributes
        • string
      • sanity

        Value from Sanity source (if exists)

        Show child attributes
        • string
    • activeSourcestringrequired

      Source of the attribute:

      • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
      • sanity: Created and managed through this API by organization administrators
    • activeValuerequired

      The value currently in effect, taken from the activeSource. This is the value that will be used in access control evaluations and role filters.

      Example:UK
      Show child attributes
      • string
  • updatedAtstring (date-time)required

    Timestamp when attributes were last updated (only returned by mutation endpoints)

    Example:2025-11-26T19:30:00.000Z

Delete User Attributes

delete/vX/organizations/{organizationId}/users/{sanityUserId}/attributes

Delete attribute values for a user using attribute keys.

This removes Sanity (API-managed) attribute values. If a SAML value exists for the same attribute key, it will become the active value and will be visible in the response (with activeSource: 'saml').

Automatic Definition Cleanup: When you delete Sanity attribute values, the system automatically cleans up Sanity definitions if:

  1. No users have Sanity values for that attribute anymore, AND
  2. A SAML definition exists for the same key

In this case, the sources will automatically revert from ['saml', 'sanity'] to ['saml'].

Sanity-only definitions (sources: ['sanity']) are never automatically cleaned up when values are deleted. They must be manually deleted via the DELETE /attribute-definitions/{key} endpoint.

Permissions

Requires sanity.organization.manage permission.

Path parameters

  • organizationIdstringrequired

    Unique identifier of the organization

    Example:o123
  • sanityUserIdstringrequired

    Unique identifier of the Sanity user

    Example:u1

Request body application/json

  • attributesarrayrequired

    Array of attribute keys to delete

    Show child attributes
    items
    • keystringrequired

      Textual name of the attribute to delete (e.g., 'location', 'department')

Responses

200

Attributes deleted successfully

  • sanityUserIdstringrequired

    ID of the user

    Example:user-xyz
  • organizationIdstringrequired

    ID of the organization

    Example:org-123
  • attributesarrayrequired
    Show child attributes
    items
    • typestringrequired

      Type of the attribute

    • keystringrequired

      Textual name of the attribute

      Example:location
    • valuesobjectrequired

      Values from all available sources. Contains 'saml' and/or 'sanity' keys with their respective values. Shows all values regardless of precedence, making it clear which values are being shadowed.

      Example
      {"saml":"US","sanity":"UK"}
      Show child attributes
      • saml

        Value from SAML source (if exists)

        Show child attributes
        • string
      • sanity

        Value from Sanity source (if exists)

        Show child attributes
        • string
    • activeSourcestringrequired

      Source of the attribute:

      • saml: Automatically synced from SSO providers (cannot be created or managed via this API)
      • sanity: Created and managed through this API by organization administrators
    • activeValuerequired

      The value currently in effect, taken from the activeSource. This is the value that will be used in access control evaluations and role filters.

      Example:UK
      Show child attributes
      • string
  • updatedAtstring (date-time)required

    Timestamp when attributes were last updated (only returned by mutation endpoints)

    Example:2025-11-26T19:30:00.000Z