Users API

The Users API allows you to manage users in your organization, including creating, updating, and deleting user accounts, as well as managing user groups and permissions.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

Endpoints

Method	Path	Description
GET	`/api/v1/users`	List all users
GET	`/api/v1/users/{email}`	Get user details
GET	`/api/v1/users/current`	Get current user
GET	`/api/v1/users/self`	Get self (general)
POST	`/api/v1/users/invite`	Invite a new user
POST	`/api/v1/users/groups/{id}`	Add user to group
GET	`/api/v1/users/membership/{id}`	Get user membership
DELETE	`/api/v1/users/{email}`	Delete a user
POST	`/api/v1/users/system_invite`	System invite

Common Response Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

List Users

Retrieve all users in your organization.

GET /api/v1/users

Query Parameters

Name	Type	Required	Description
`role`	string	No	Filter by role
`group`	string	No	Filter by group
`limit`	integer	No	Maximum number of users to return (default: 50)
`page`	integer	No	Page number for pagination

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "email": "user@example.com",
    "name": "John Doe",
    "role": "admin",
    "groups": ["developers", "admins"],
    "created_at": "2023-01-01T00:00:00Z",
    "last_login": "2023-01-15T12:00:00Z",
    "status": "active",
    "metadata": {
      "department": "Engineering",
      "title": "Senior Developer"
    }
  }
]

Get User Details

Retrieve details for a specific user.

GET /api/v1/users/{email}

Path Parameters

Name	Type	Required	Description
`email`	string	Yes	Email of the user

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin",
  "groups": ["developers", "admins"],
  "created_at": "2023-01-01T00:00:00Z",
  "last_login": "2023-01-15T12:00:00Z",
  "status": "active",
  "metadata": {
    "department": "Engineering",
    "title": "Senior Developer"
  }
}

Get Current User

Retrieve details for the currently authenticated user.

GET /api/v1/users/current

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "email": "current@example.com",
  "name": "Current User",
  "role": "admin",
  "groups": ["developers", "admins"],
  "created_at": "2023-01-01T00:00:00Z",
  "last_login": "2023-01-15T12:00:00Z",
  "status": "active",
  "metadata": {
    "department": "Engineering",
    "title": "Senior Developer"
  }
}

Invite User

Invite a new user to your organization.

POST /api/v1/users/invite

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "email": "newuser@example.com",
  "name": "New User",
  "role": "member",
  "groups": ["developers"],
  "metadata": {
    "department": "Engineering",
    "title": "Developer"
  }
}

Required Fields

email: Email address of the user to invite
role: Role to assign to the user ("admin", "member", "viewer")

Response

{
  "email": "newuser@example.com",
  "name": "New User",
  "role": "member",
  "status": "invited",
  "invited_at": "2023-01-15T12:00:00Z",
  "invited_by": "admin@example.com"
}

Add User to Group

Add a user to a specific group.

POST /api/v1/users/groups/{id}

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	ID of the group

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "email": "user@example.com"
}

Response

{
  "group_id": "group-123",
  "email": "user@example.com",
  "added_at": "2023-01-15T12:00:00Z",
  "added_by": "admin@example.com"
}

Get User Membership

Retrieve group membership information for a user.

GET /api/v1/users/membership/{id}

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	ID of the user

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "user_id": "user-123",
  "groups": [
    {
      "id": "group-123",
      "name": "developers",
      "role": "member",
      "joined_at": "2023-01-01T00:00:00Z"
    }
  ]
}

Delete User

Delete a user from your organization.

DELETE /api/v1/users/{email}

Path Parameters

Name	Type	Required	Description
`email`	string	Yes	Email of the user to delete

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

A successful delete operation returns an HTTP 200 status with no response body.

System Invite

Create a system-level user invitation.

POST /api/v1/users/system_invite

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "email": "system@example.com",
  "role": "system",
  "metadata": {
    "purpose": "system_integration"
  }
}

Response

{
  "email": "system@example.com",
  "role": "system",
  "status": "invited",
  "invited_at": "2023-01-15T12:00:00Z",
  "invited_by": "system"
}

User management is a critical part of your organization's security. Make sure to regularly review user roles and remove access for users who no longer need it.

Example Usage

# List all users
curl -X GET "https://api.kubiya.ai/api/v1/users" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get user by email
curl -X GET "https://api.kubiya.ai/api/v1/users/user@example.com" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get current user
curl -X GET "https://api.kubiya.ai/api/v1/users/current" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Invite new user
curl -X POST "https://api.kubiya.ai/api/v1/users/invite" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "role": "member",
    "groups": ["developers"],
    "metadata": {
      "department": "Engineering",
      "title": "Developer"
    }
  }'
 
# Add user to group
curl -X POST "https://api.kubiya.ai/api/v1/users/groups/group-123" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
 
# Get user membership
curl -X GET "https://api.kubiya.ai/api/v1/users/membership/user-123" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Delete user
curl -X DELETE "https://api.kubiya.ai/api/v1/users/user@example.com" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# System invite
curl -X POST "https://api.kubiya.ai/api/v1/users/system_invite" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "system@example.com",
    "role": "system",
    "metadata": {
      "purpose": "system_integration"
    }
  }'

Common Errors

HTTP Status	Description
400	Bad Request - Invalid request body or missing required fields
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to perform this action
404	Not Found - The specified user was not found
409	Conflict - A user with the same email already exists
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After managing users, you can:

Set up Agents for your users to interact with
Configure Sources to provide tools
Create Webhooks to handle user events

Users API

On this page