---
name: supplier-users
description: >
  Instructs AI agents how to manage supplier users in Kyriba's Working Capital
  module. Supplier users are external portal accounts for suppliers.
version: 1.0.0
scopes:
  - supplier-user-scope
authors:
  - kyriba
tags:
  - kyriba
  - working-capital
  - workcap
  - supplier-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: Supplier Users (Working Capital)

---

## Required Kyriba Permission

```
supplier-user-scope
```

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

---

## What are Supplier Users?

Supplier users are external portal accounts for suppliers who access Kyriba's Working Capital portal to view invoices, request early payments, and manage their financing activities.

>  This API is part of the **Working Capital** module (`workcap`). Endpoints return `404` if this module is not enabled on your environment.

---

##  Non-Standard Base Path

This API uses a Swagger 2.0 spec with:

```
basePath: /v1/workcap/supplier-users
```

Full URL: `https://api.demo.kyriba.com/v1/workcap/supplier-users`

---

## Endpoints

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

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/workcap/supplier-users` | List supplier users |
| `POST` | `/v1/workcap/supplier-users` | Create a new supplier user |
| `GET` | `/v1/workcap/supplier-users/{ref}` | Get a specific supplier user |
| `PUT` | `/v1/workcap/supplier-users/{ref}` | Update a specific supplier user |
| `DELETE` | `/v1/workcap/supplier-users/{ref}` | Delete a specific supplier user |

---

## Filterable & Sortable Fields

```
code, uuid, interfaceCode, description, firstName, lastName, ssoIdentity, email,
thirdParty.code, thirdParty.uuid, thirdPartyName,
accessProfile.code, accessProfile.uuid,
companyOwnership.code, companyOwnership.uuid,
systemAdministrator, creationDate, lastUpdateDate
```

---

## Pagination

Uses **standard** `page.limit` / `page.offset` parameters.

---

## Example Requests

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

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**Filter by third party (supplier):**
```
GET /v1/workcap/supplier-users?filter=thirdParty.code==SUPPLIER_A
```

**Create a supplier user:**
```http
POST /v1/workcap/supplier-users
Content-Type: application/json

{
  "code": "SUSR_JDOE",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@supplier-a.com",
  "thirdParty": { "code": "SUPPLIER_A" },
  "accessProfile": { "code": "ACCESS_PROF_01" },
  "companyOwnership": { "code": "COMP_FR" }
}
```

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

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique supplier user code |
| `uuid` | System-generated identifier |
| `interfaceCode` | External system reference code |
| `firstName` / `lastName` | User name. **Can be `null`**. |
| `email` | Portal login email |
| `thirdParty` | Linked third party (supplier) `{ "code": "...", "uuid": "..." }` |
| `accessProfile` | Assigned access profile `{ "code": "...", "uuid": "..." }` |
| `companyOwnership` | Owning company `{ "code": "...", "uuid": "..." }` |
| `description1` / `description2` | Free-text description fields |
| `ssoIdentity` | SSO login identity |
| `systemAdministrator` | `true` if the user has admin rights |
| `timeZone` | User time zone string |
| `preferredContactChannel` | e.g. `OFFICE_PHONE`, `MOBILE_PHONE` |

---

##  Common Mistakes

| Wrong | Correct |
|---|---|
| Filter `supplier.code==X` | Filter `thirdParty.code==X` |
| Field `supplier` | Field `thirdParty` |
| Field `active` | Does not exist in this API |

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. `PUT` replaces the full user object - always `GET` first
3. `DELETE` permanently removes the supplier portal account
4. Uniqueness enforced on `code` and `email`

---

## Error Reference

| Status | Meaning |
|---|---|
| `400` | Missing required fields or validation error. Body: `{ "error": { "code": "...", "message": "..." } }` |
| `401` | Authentication required |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Supplier user not found or Working Capital module not enabled |
| `409` | Code or email already exists |
| `415` | Wrong `Content-Type` |
| `500` | Internal server error |

---

## OpenAPI Spec & Postman Collection

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