Users API

The Users API allows you to manage user accounts within your Xata organization, including listing, retrieving, updating, and deleting user accounts. All endpoints require authentication via API key or OIDC.

Authentication

All endpoints require authentication. You can authenticate using:

• API Key: Include your API key in the Authorization header: Authorization: Bearer <your-api-key>
• OIDC: Use OIDC tokens for authentication

Required scopes for different operations:

• user:read: Read user information and list users
• user:write: Update and delete user accounts

List users

Retrieves a list of all users in an organization.

GET /users

Summary

Returns a list of all users in the authenticated user's organization, including basic profile information such as ID, email, name, and timestamps.

Response

Status: 200 OK

{
  "users": [
    {
      "id": "user_123",
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Response schema

Get user

Retrieves detailed information about a specific user.

GET /users/{userID}

Summary

Returns comprehensive information about a specific user by their ID, including all profile details and account metadata.

Path parameters

Response

Status: 200 OK

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Update user

Updates user information within an organization.

PATCH /users/{userID}

Summary

Updates the user's profile information such as name and email address. Note that some fields may be restricted based on the authenticated user's permissions.

Path parameters

Request body

{
  "name": "Updated User Name",
  "email": "updated@example.com"
}

Request body parameters

Response

Status: 200 OK

{
  "id": "user_123",
  "email": "updated@example.com",
  "name": "Updated User Name",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Delete user

Removes a user from an organization.

DELETE /users/{userID}

Summary

Permanently removes a user from the organization. This action cannot be undone and will revoke all access for the specified user.

Path parameters

Response

Status: 204 No Content

No response body is returned on successful deletion.

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "id": "error_identifier",
  "message": "Human-readable error message explaining the issue"
}

Common error responses

Schema Reference

Core Data Models

User

Basic user information.

UserID

Unique identifier for a user account.

UserUpdateRequest

Request body for updating user details.