---
name: users
description: >
  Instructs AI agents how to create, read, update, and delete users in Kyriba.
  Users are business users who access the Kyriba platform. Covers user provisioning,
  permission flags, and working hours configuration.
version: 1.0.0
scopes:
  - user-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - users
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Users

---

## Required Kyriba Permission

```
user-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## Base Path

```
/v1/users
```

---

## Endpoints

`{ref}` accepts either `uuid` or `code`.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/users` | List users |
| `POST` | `/v1/users` | Create a new user |
| `GET` | `/v1/users/{ref}` | Get a specific user |
| `PUT` | `/v1/users/{ref}` | Update a specific user |
| `DELETE` | `/v1/users/{ref}` | Delete a specific user |
| `GET` | `/v1/users/documented-fields` | List fields available for data import |

---

## Filterable & Sortable Fields

```
code, uuid, interfaceCode, lastName, firstName,
email, accessProfile.code, accessProfile.uuid, language.code,
companyOwnership.code, companyOwnership.uuid
```

---

## Example Requests

**List all users:**
```
GET /v1/users?page.limit=100&page.offset=0&sort=code
```

**Find users by company:**
```
GET /v1/users?filter=ownershipCompany.code==COMP_FR
```

**Find user by email:**
```
GET /v1/users?filter=email==john.doe@company.com
```

**Create a user (minimal):**
```http
POST /v1/users
Content-Type: application/json

{
  "code": "JDOE",
  "interfaceCode": "USER001",
  "lastName": "Doe",
  "firstName": "John",
  "email": "john.doe@company.com",
  "language": { "code": "EN" },
  "companyOwnership": { "code": "COMP_FR" },
  "accessProfile": { "code": "TREASURY_USER" }
}
```

**Create response:** `{ "uuid": "..." }`

**List response:**
```json
{
  "metadata": { "total": 50, "count": 50, "limit": 100, "offset": 0 },
  "results": [
    {
      "uuid": "...",
      "code": "JDOE",
      "interfaceCode": "USER001",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@company.com",
      "description": null,
      "accessProfile": { "uuid": "...", "code": "TREASURY_USER" },
      "dataPermissionProfile": { "uuid": "...", "code": "ALL_DATA" },
      "companyOwnership": { "uuid": "...", "code": "COMP_FR" },
      "active": true,
      "apiUser": false,
      "paymentAdministrator": false,
      "systemAdministrator": false,
      "lastLoginDate": null
    }
  ]
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique user code |
| `uuid` | System-generated identifier |
| `interfaceCode` | External system code for ERP integration |
| `lastName` / `firstName` | User name. **Can be `null`**. |
| `email` | Login email address. **Can be `null`** for service accounts. |
| `description` | Optional label. **Can be `null`**. |
| `language` | UI language `{ "code": "EN" }` |
| `companyOwnership` | Company the user belongs to `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `accessProfile` | Access profile `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `dataPermissionProfile` | Data permission profile `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `active` | `true` if the user account is active |
| `apiUser` | `true` if this is an API client account |
| `paymentAdministrator` | `true` if user has payment admin rights |
| `systemAdministrator` | `true` if user has system admin rights |
| `lastLoginDate` | ISO datetime of last login. **Can be `null`**. |

>  The full user object also contains working hours (Monday–Sunday open/close times) and additional permission flags. Use `GET /v1/users/documented-fields` to discover the complete field list before a PUT update.

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. Uniqueness enforced on `code` and `interfaceCode`
3. `PUT` replaces the full user object - always `GET` first to avoid wiping existing fields
4. `DELETE` permanently removes the user and all associated settings
5. Filter by company: use `companyOwnership.code` (not `ownershipCompany.code`)
6. Filter by profile: use `accessProfile.code` (not `profile.code`)

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Created - returns `{ "uuid": "..." }` |
| `400` | Missing required fields |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | User not found |
| `409` | `code` or `interfaceCode` already exists |
| `415` | Wrong Content-Type (must be `application/json`) |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/users/users.yaml`
- Postman: `https://developer.kyriba.com/static/apis/users/users-postman-collection.json`