Users

Users are the foundational concept in the Connectivity API. Each user represents an individual end-user or tenant in your application and serves as a container for credentials and integration instances.

Understanding Users

The User Model

In Connectivity API, a user is:

An isolation boundary: Each user’s credentials and data are completely isolated from other users
A credential container: Users own credentials for one or more third-party connectors
A tenant identifier: Maps directly to end-users, organizations, or workspaces in your application
Persistent: Once created, users persist until explicitly deleted

User-to-Application Mapping

The relationship between your application’s users and Connectivity API users should be 1:1: Best Practice: Create a Connectivity API user for each end-user in your system when they first need to connect an integration. Store the mapping between your user ID and the Connectivity API userId in your database.

Creating Users

Basic User Creation

Create a user by providing a unique username and optional full name:

curl -X POST https://production.runalloy.com/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user_jane_001",
    "fullName": "Jane Doe"
  }'

Response:

{
  "userId": "68c3229752345278627ae373"
}

The userId is the unique identifier you’ll use for all subsequent operations involving this user.

Username Requirements

Must be unique across your account
Recommended format: Use a combination of your internal user ID or email
Examples:
- user_12345 (based on your internal user ID)
- jane@example.com (based on their email)
- jane_doe_acme_corp (based on email + organization)
- org_456_user_789 (multi-tenant approach)

Request Parameters

Parameter	Type	Required	Description
`username`	string	Yes	Unique identifier for the user
`fullName`	string	No	Human-readable name for the user

User Lifecycle Management

Storing User Mappings

After creating a Connectivity API user, store the mapping in your database:

// Example: Store mapping in your database
await database.users.update({
  where: { email: 'jane@company.com' },
  data: {
    alloyUserId: '68c3229752345278627ae373'
  }
});

This allows you to:

Retrieve the userId when executing operations
Track which users have connected integrations
Clean up credentials when users delete their accounts

Retrieving User Information

Get details about a specific user:

curl -X GET https://production.runalloy.com/users/68c3229752345278627ae373 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}"

Response:

{
  "userId": "68c3229752345278627ae373",
  "username": "user_jane_001",
  "fullName": "Jane Doe",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Listing All Users

Retrieve all users in your account:

curl -X GET https://production.runalloy.com/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}"

Response:

{
  "users": [
    {
      "userId": "68c3229752345278627ae373",
      "username": "user_jane_001",
      "fullName": "Jane Doe",
      "createdAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "userId": "68ccf0183ebc2162c7e476fc",
      "username": "user_john_002",
      "fullName": "John Smith",
      "createdAt": "2025-01-16T14:20:00.000Z"
    }
  ]
}

Updating Users

Update a user’s information:

curl -X PUT https://production.runalloy.com/users/68c3229752345278627ae373 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jane Smith"
  }'

Note: The username field cannot be changed after creation.

Deleting Users

Delete a user and all associated credentials:

curl -X DELETE https://production.runalloy.com/users/68c3229752345278627ae373 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}"

Warning: This operation:

Permanently deletes the user
Revokes and deletes all credentials associated with the user
Cannot be undone

Always ensure you have user consent before deleting their user, as this will disconnect all their integrations.

User Context in Operations

Specifying User Context

Most operations require specifying which user’s context to operate within using the x-alloy-userid header:

curl -X POST https://production.runalloy.com/connectors/hubspot/actions/createContact/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}" \
  -H "x-alloy-userid: 68c3229752345278627ae373" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialId": "68d2e2fd5aa2c97c2ae99c24",
    "requestBody": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    }
  }'

The x-alloy-userid header ensures:

Operations execute with the correct user’s credentials
Data isolation between users
Proper authorization and access control

When User Context Is Required

The x-alloy-userid header is required for:

Executing actions: All operations that interact with third-party platforms
Managing credentials: Creating, updating, or listing a user’s credentials
User-specific queries: Any operation that acts on behalf of a specific user

Error Handling

Common Errors

Duplicate Username

{
  "error": {
    "source": "CONNECTIVITY_API",
    "code": "DUPLICATE_USERNAME",
    "message": "User with this username already exists",
    "details": {
      "username": "user_jane_001"
    }
  }
}

Solution: Use a different username. Consider appending a timestamp or UUID if needed.

User Not Found

{
  "error": {
    "source": "CONNECTIVITY_API",
    "code": "INVALID_USER",
    "message": "User not found",
    "details": {
      "userId": "invalid_user_id"
    }
  }
}

Solution: Verify the userId is correct and the user hasn’t been deleted.

Missing User Context

{
  "error": {
    "source": "CONNECTIVITY_API",
    "code": "MISSING_USER_CONTEXT",
    "message": "x-alloy-userid header is required for this operation"
  }
}

Solution: Include the x-alloy-userid header in your request.

Best Practices

Username Conventions

Be consistent: Use the same naming pattern across all users
Include context: Add organization or tenant info for multi-tenant apps
Avoid PII: Don’t use email addresses directly if avoidable
Plan for scale: Use IDs that won’t conflict as your user base grows

Testing

Test User Creation

Create test users with a clear naming convention:

curl -X POST https://production.runalloy.com/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test_user_001",
    "fullName": "Test User"
  }'

Clean Up Test Users

Always clean up test users after testing:

curl -X DELETE https://production.runalloy.com/users/TEST_USER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: {API_VERSION}"

Next Steps

Learn about Credentials and how to attach them to users
Explore Authentication patterns
Start Executing Actions on behalf of users

Getting Started

Understanding Users

The User Model

User-to-Application Mapping

Creating Users

Basic User Creation

Username Requirements

Request Parameters

User Lifecycle Management

Storing User Mappings

Retrieving User Information

Listing All Users

Updating Users

Deleting Users

User Context in Operations

Specifying User Context

When User Context Is Required

Error Handling

Common Errors

Duplicate Username

User Not Found

Missing User Context

Best Practices

Username Conventions

Testing

Test User Creation

Clean Up Test Users

Next Steps

Need Help?

Getting Started

​Understanding Users

​The User Model

​User-to-Application Mapping

​Creating Users

​Basic User Creation

​Username Requirements

​Request Parameters

​User Lifecycle Management

​Storing User Mappings

​Retrieving User Information

​Listing All Users

​Updating Users

​Deleting Users

​User Context in Operations

​Specifying User Context

​When User Context Is Required

​Error Handling

​Common Errors

​Duplicate Username

​User Not Found

​Missing User Context

​Best Practices

​Username Conventions

​Testing

​Test User Creation

​Clean Up Test Users

​Next Steps

​Need Help?

Understanding Users

The User Model

User-to-Application Mapping

Creating Users

Basic User Creation

Username Requirements

Request Parameters

User Lifecycle Management

Storing User Mappings

Retrieving User Information

Listing All Users

Updating Users

Deleting Users

User Context in Operations

Specifying User Context

When User Context Is Required

Error Handling

Common Errors

Duplicate Username

User Not Found

Missing User Context

Best Practices

Username Conventions

Testing

Test User Creation

Clean Up Test Users

Next Steps

Need Help?