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

# Users

> Learn how to create and manage users in the Connectivity API

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:

```mermaid theme={null}
graph LR
    A[Your User] -->|Maps to| B[Alloy User: user_jane_001]
    B -->|Owns| C[HubSpot Credential]
    B -->|Owns| D[Salesforce Credential]
    B -->|Owns| E[Notion Credential]
```

**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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```javascript theme={null}
// 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:

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

**Response:**

```json theme={null}
{
  "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:

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

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](/connectivity-api/credentials) and how to attach them to users
* Explore [Authentication](/connectivity-api/authentication) patterns
* Start [Executing Actions](/connectivity-api/quick-start) on behalf of users

## Need Help?

* [API Reference](/reference/connectivity-api/connectivity-api)
* [Support](mailto:support@runalloy.com)