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

# User Attributes

User attributes are key-value pairs attached to a user that control how WisdomAI filters and personalizes data for their session. They are used for:

* **Parameterized connections**: matching a user's attributes against `credentialMappings.attributeMatch` to resolve the right data source credentials.
* **Row-level authorization**: referencing attributes in filter rules to restrict which rows a user can see.
* **Personalized data access**: passing session-specific context (e.g., a selected account or region) at impersonation time.

## Attribute sources

Every attribute has a `source` field that indicates where it came from.

| Source     | Set by                                   | Mutable via API | Description                                      |
| ---------- | ---------------------------------------- | :-------------: | ------------------------------------------------ |
| `DATABASE` | API (`createUsers`, `setUserAttributes`) |       Yes       | Persistent attributes stored against the user    |
| `JWT`      | SSO identity provider (SAML/OIDC claims) |        No       | Read-only attributes from the user's login token |

When the same key exists in both sources, the `DATABASE` value takes precedence — unless a transient (session-specific) attribute is passed at impersonation time, which overrides both for that session only.

## Setting attributes

Attributes can be set at three points in a user's lifecycle: when the user is first provisioned, updated later via API, or passed at impersonation time for session-specific context.

### At creation time

Pass `userAttributes` in `CreateUsersInput` when provisioning the user. This is the most efficient option when you know the attributes upfront:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "emails": ["alice@yourcompany.com"],
        "workspaceID": "workspace_123",
        "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
        "sendWelcomeEmail": true,
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "us-east" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

<Note>
  Replace `{ACCOUNT}.wisdom.ai` with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

### Updating later

Call `setUserAttributes` to replace the user's DATABASE-sourced attributes after they've been created:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation SetUserAttributes($input: SetUserAttributesInput!) { setUserAttributes(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "userId": "user_abc123",
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "us-west" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

<Warning>
  `setUserAttributes` **replaces all DATABASE-sourced attributes**. Include every attribute the user should have after the call — omitting an attribute removes it.
</Warning>

### At impersonation time (transient)

Pass `attributes` in `impersonateUser` for session-only overrides. These are applied for the duration of the JWT only and are never persisted:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!, $attributes: [UserAttributeInput!]) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail, attributes: $attributes) }",
    "variables": {
      "accessToken": "<your_access_token>",
      "userEmail": "alice@yourcompany.com",
      "attributes": [
        { "key": "report_context", "value": "q3-summary" }
      ]
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

Transient attributes override DATABASE-sourced values for that session. They are useful for passing request-scoped context that should not be stored on the user.

## Choosing the right approach

| Use case                                                      | Recommended approach                                                 |
| ------------------------------------------------------------- | -------------------------------------------------------------------- |
| Attributes that are stable for the user (e.g., `account_id`)  | Set at creation via `createUsers`, or update via `setUserAttributes` |
| Attributes that change per request or should not be persisted | Pass as Transient (Session) attributes in `impersonateUser`          |
| Attributes sourced from SSO claims                            | Read automatically from the JWT — no action needed                   |

## Related articles

<CardGroup cols={2}>
  <Card title="Create Users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Set attributes at provisioning time
  </Card>

  <Card title="Set User Attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Update DATABASE-sourced attributes on existing users
  </Card>

  <Card title="Impersonate User" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Pass transient attributes at session time
  </Card>

  <Card title="List Users" icon="users" href="/integrations/graphql-api/queries/user/list-users">
    Inspect a user's current attributes and their source
  </Card>
</CardGroup>