Users

The Users API allows you to manage users in your Airclou organization. You can create, retrieve, update, and delete users, as well as manage their roles and permissions.

The user object

A user represents an individual with access to your Airclou organization.

Attributes

Attribute	Type	Description
id	string	Unique identifier for the user
email	string	User’s email address (unique)
name	string	User’s full name
avatar_url	string	URL to user’s profile picture
role	string	User role: owner, admin, member, or viewer
status	string	Account status: active, invited, or suspended
created_at	timestamp	When the user was created
updated_at	timestamp	When the user was last updated
last_login_at	timestamp	When the user last logged in

Example object

{
  "id": "usr_1234567890",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "avatar_url": "https://app.airclou.com/playbook/avatars/usr_1234567890",
  "role": "admin",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-11-01T14:20:00Z",
  "last_login_at": "2025-11-06T09:15:00Z"
}

---

List all users

Retrieve a paginated list of users in your organization.

Endpoint

GET /playbook/api/v1/users

Query parameters

Parameter	Type	Description
limit	integer	Number of users to return (1-100). Default: 50
cursor	string	Pagination cursor from previous response
role	string	Filter by role: owner, admin, member, or viewer
status	string	Filter by status: active, invited, or suspended
search	string	Search by name or email

Example request

curl "https://app.airclou.com/playbook/api/v1/users?limit=25&role=admin" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "usr_1234567890",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "admin",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "usr_0987654321",
      "email": "jane.smith@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "status": "active",
      "created_at": "2025-02-20T15:45:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InVzcl8wOTg3NjU0MzIxIn0",
    "has_more": true,
    "total_count": 156
  }
}

---

Retrieve a user

Get details about a specific user by ID.

Endpoint

GET /playbook/api/v1/users/{user_id}

Path parameters

Parameter	Type	Description
user_id	string	The ID of the user to retrieve

Example request

curl "https://app.airclou.com/playbook/api/v1/users/usr_1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "usr_1234567890",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "avatar_url": "https://app.airclou.com/playbook/avatars/usr_1234567890",
  "role": "admin",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-11-01T14:20:00Z",
  "last_login_at": "2025-11-06T09:15:00Z"
}

---

Create a user

Create a new user and send them an invitation email.

Endpoint

POST /playbook/api/v1/users

Request body

Field	Type	Required	Description
email	string	Yes	User’s email address
name	string	Yes	User’s full name
role	string	No	User role (default: member)
send_invitation	boolean	No	Send invitation email (default: true)

Example request

curl -X POST "https://app.airclou.com/playbook/api/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "name": "New User",
    "role": "member",
    "send_invitation": true
  }'

Example response

{
  "id": "usr_9876543210",
  "email": "new.user@example.com",
  "name": "New User",
  "avatar_url": null,
  "role": "member",
  "status": "invited",
  "created_at": "2025-11-06T10:00:00Z",
  "updated_at": "2025-11-06T10:00:00Z",
  "last_login_at": null
}

---

Update a user

Update an existing user’s information.

Endpoint

PATCH /playbook/api/v1/users/{user_id}

Path parameters

Parameter	Type	Description
user_id	string	The ID of the user to update

Request body

Field	Type	Description
name	string	User’s full name
role	string	User role: owner, admin, member, or viewer
status	string	Account status: active or suspended

Example request

curl -X PATCH "https://app.airclou.com/playbook/api/v1/users/usr_1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "role": "admin"
  }'

Example response

{
  "id": "usr_1234567890",
  "email": "john.doe@example.com",
  "name": "John Smith",
  "avatar_url": "https://app.airclou.com/playbook/avatars/usr_1234567890",
  "role": "admin",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-11-06T10:30:00Z",
  "last_login_at": "2025-11-06T09:15:00Z"
}

---

Delete a user

Permanently delete a user from your organization.

Endpoint

DELETE /playbook/api/v1/users/{user_id}

Path parameters

Parameter	Type	Description
user_id	string	The ID of the user to delete

Example request

curl -X DELETE "https://app.airclou.com/playbook/api/v1/users/usr_1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

204 No Content

Note: Deleting a user is permanent and cannot be undone. Consider suspending the user instead if you might need to restore access later.

---

Roles and permissions

Users can have one of four roles, each with different permission levels:

Owner

• Full access to all resources
• Can manage billing and subscriptions
• Can delete the organization
• Only one owner per organization

Admin

• Can manage users and teams
• Can create and delete projects
• Can view billing information
• Cannot delete the organization

Member

• Can create and edit projects
• Can invite other members
• Cannot manage billing or users

Viewer

• Read-only access to all resources
• Cannot create or modify anything
• Useful for clients or stakeholders

Error responses

Common errors when working with the Users API:

400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email address format",
    "field": "email"
  }
}

404 Not Found

{
  "error": {
    "code": "resource_not_found",
    "message": "User not found"
  }
}

409 Conflict

{
  "error": {
    "code": "resource_already_exists",
    "message": "A user with this email already exists"
  }
}