Users API

Keito provides a workspace-scoped team directory for administrator integrations. The directory follows Harvest’s distinction between reporting roles and permission roles, and includes the workspace-specific capacity needed by payroll and reporting tools.

Permissions

Credential and identity	/users	/roles and /users/{id}/teammates
Full-access key for an Owner or Administrator	Full team directory	Allowed
Cost-rate automation key with users:read for an Owner or Administrator	Full team directory	Allowed
Personal read-only sync key	Reduced compatibility directory	Not allowed
Other identities	Not allowed	Not allowed

Every response is limited to the workspace selected by the authenticated credential and Keito-Account-Id header. A full-access key does not make its user an Administrator.

List Workspace Users

GET /api/v2/users

For administrator directory calls, the supported query parameters are is_active, employee_id, page, and per_page. Those results are ordered by the user’s creation time, newest first. Personal sync keys use the separate filters and ordering documented below.

curl "https://app.keito-test.com/api/v2/users?is_active=true&per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

An administrator response contains a users array in the standard API v2 pagination envelope:

{
  "users": [
    {
      "id": "user_id",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "employee_id": "EMP-100",
      "is_active": true,
      "is_contractor": false,
      "weekly_capacity": 126000,
      "currency": "GBP",
      "roles": ["Developer"],
      "access_roles": ["member"],
      "created_at": "2026-09-15T08:00:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "links": {
    "first": "...",
    "next": null,
    "previous": null,
    "last": "..."
  }
}

weekly_capacity is the member’s capacity for this workspace in seconds. For example, 35 hours is 126000.

roles contains active custom reporting-role names such as Developer or Designer. These labels do not grant access. access_roles contains permission roles such as member, manager, or administrator; use this field for authorization decisions.

If an existing integration checked roles for permission names, migrate that check to access_roles.

Imported placeholder members use their original imported email when Keito can safely recover it. Contact-erased members always remain redacted; erasure takes precedence over imported identity data. Cost rates and billable rates are never included in this directory.

Personal read-only sync keys receive their existing reduced /users shape. It omits email, capacity, custom reporting roles, and management relationships, and retains permission values in roles for compatibility. See Personal Read-Only Sync Keys for that exact contract.

List Reporting Roles

GET /api/v2/roles

Returns custom reporting roles and the users who have both a current workspace membership and an unsuppressed assignment to that role. A user’s active or archived status does not change whether that assignment is listed.

curl "https://app.keito-test.com/api/v2/roles?per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

{
  "roles": [
    {
      "id": "role_id",
      "name": "Developer",
      "user_ids": ["user_id"],
      "created_at": "2026-09-15T08:00:00.000Z",
      "updated_at": "2026-09-15T08:00:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "links": {
    "first": "...",
    "next": null,
    "previous": null,
    "last": "..."
  }
}

The endpoint supports page and per_page and returns roles newest first. Personal read-only sync keys cannot call this endpoint.

List a Manager’s Teammates

GET /api/v2/users/{id}/teammates

Returns the minimal identities directly assigned to a manager in the selected workspace.

curl "https://app.keito-test.com/api/v2/users/$MANAGER_USER_ID/teammates?per_page=100" \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

{
  "teammates": [
    {
      "id": "user_id",
      "first_name": "Alex",
      "last_name": "Smith",
      "email": "alex@example.com"
    }
  ],
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "links": {
    "first": "...",
    "next": null,
    "previous": null,
    "last": "..."
  }
}

The endpoint supports page and per_page. A missing or foreign-workspace user returns 404 Not Found. A same-workspace user without the Manager permission role returns 422 Unprocessable Entity. Personal read-only sync keys cannot call this endpoint.

Current User

GET /api/v2/users/me

Returns the authenticated identity. This existing endpoint has a separate response contract from the administrator directory:

• Full-access integration keys return the user profile and resolved company.
• Personal read-only sync keys return a reduced profile and read capabilities. They intentionally omit company and user_type.

curl "https://app.keito-test.com/api/v2/users/me" \
  -H "Authorization: Bearer kto_xxxxx" \
  -H "Keito-Account-Id: your_company_id"

Full-access integration key response shape:

{
  "id": "user_id_here",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "roles": ["administrator", "manager", "member"],
  "user_type": "human",
  "company": {
    "id": "company_id_here",
    "name": "Acme Consulting"
  }
}

For the exact reduced personal sync response, see Personal Read-Only Sync Keys. Do not require company when consuming that key type.