Identifier Model

Understand Weavz IDs, your external IDs, connection selectors, and persistence namespace keys.

Identifier Model

Weavz has several fields that look similar but belong to different primitives. Use this page as the source of truth when deciding which ID to store, pass, or show in your product.

Quick Reference

Term	Meaning	Use it when
`endUser.id`	Weavz internal end-user UUID	Calling `/api/v1/end-users/:id`, updating an end user, deleting an end user, or generating an end-user connect token
`endUser.externalId`	Your application's user ID for that end user, unique inside a workspace	Creating end users and resolving per-user credentials during execution
Public request `endUserId`	Selector field that normally carries `endUser.externalId`	Executing actions, enabling triggers, resolving properties, creating user-scoped connections, and issuing MCP end-user tokens unless the endpoint explicitly says UUID
`connection.id`	Weavz internal connection UUID	Pinning a fixed connection on a workspace integration or MCP tool
`connection.externalId`	Your connection selector	Looking up or reusing one specific connection by a stable customer-defined key
`connectionExternalId`	Request field containing `connection.externalId`	Directly selecting one connection for action execution, trigger setup, or property resolution
`workspaceIntegrationId`	Weavz UUID of a configured workspace integration	Selecting the exact configured integration instance when the same integration appears more than once
`integrationAlias`	Configured workspace integration alias	Selecting a workspace integration by stable human-readable name after setup
`settings.persistence.externalId`	External namespace key	Scoping built-in Storage/KV/state to a tenant, project, job, or session namespace

End User IDs

An end user is the Weavz record for a person using your product. The external ID is not a separate user primitive; it is your product's identifier stored on that end-user record.

Each end user has two identifiers:

id: the Weavz UUID for the end-user record.
externalId: your application's user ID, such as user_123.

Create the end user with your application's user ID:

json

{
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "user_123",
  "displayName": "Ava Chen"
}

Use the returned endUser.id for end-user CRUD and connect-token path parameters:

http

POST /api/v1/end-users/8f70d9f8-2f44-46b7-a67d-8a1a8f4f9e32/connect-token

Use the end user's externalId when public execution APIs ask for endUserId:

json

{
  "integrationName": "slack",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "integrationAlias": "slack_user",
  "endUserId": "user_123",
  "input": {
    "channel": "C0123456789",
    "text": "Hello from Ava's Slack account"
  }
}

MCP end-user token endpoints accept the end user's external ID and also support the internal UUID for dashboard-created users. Other public execution surfaces should be treated as external-ID selectors unless the endpoint explicitly says it wants a UUID path parameter.

Connection IDs

A connection stores credentials for one integration. It also has two identifiers:

id: the Weavz UUID for the connection.
externalId: your stable selector for that connection, such as conn_slack_prod.

Use connection.id when pinning a fixed connection:

json

{
  "integrationName": "slack",
  "alias": "slack_bot",
  "connectionStrategy": "fixed",
  "connectionId": "9b2b73f7-b575-42b1-9a8f-c233dff5127d"
}

Use connectionExternalId when you want one API call to target a connection by its external selector:

json

{
  "integrationName": "slack",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "connectionExternalId": "conn_slack_prod",
  "input": {
    "channel": "C0123456789",
    "text": "Hello from the production Slack connection"
  }
}

Do not use connection externalId as your default user identity model. Use first-class end users for per-user credentials.

Persistence Namespace Keys

Built-in stateful workspace integrations such as Storage and KV Store can store data in three scopes:

Scope	Meaning
`end_user`	Data is scoped to the end user selected by public `endUserId`
`workspace`	Data is shared across the workspace
`external`	Data is scoped to a custom namespace key configured as `settings.persistence.externalId`

The persistence externalId is a namespace key, not a user ID and not a connection ID:

json

{
  "integrationName": "kv-store",
  "alias": "tenant_state",
  "settings": {
    "persistence": {
      "scope": "external",
      "externalId": "tenant_acme"
    }
  }
}

Recommended Defaults

Store endUser.id and endUser.externalId in your product when using per-user connections.
Use endUser.externalId as public endUserId during execution.
Use connection externalId only as a direct connection selector.
Prefer workspaceIntegrationId when selecting a repeated integration instance programmatically.
Use integrationAlias when you want a stable, readable selector.
Call a persistence externalId an external namespace key in product copy and examples.