---
name: supplier-service-accesses
description: >
  Instructs AI agents how to manage Supplier Service Accesses in Kyriba.
  A service access record controls which Working Capital services
  (invoicing, early payment, discounting, auction) a specific buyer-supplier
  pair can use.
version: 1.0.0
scopes:
  - supplier-service-access-scope
authors:
  - kyriba
tags:
  - kyriba
  - working-capital
  - workcap
  - supplier
  - 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 Service Accesses

---

## Required Kyriba Permission

```
supplier-service-access-scope
```

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

>  Scope is singular - `supplier-service-access-scope`, not `supplier-service-accesses-scope`.

---

## What are Supplier Service Accesses?

A Supplier Service Access record defines which Working Capital finance services are enabled between a specific **buyer** (company) and **supplier** (third party). Each record is unique per buyer + third-party combination.

>  This API is part of the **Working Capital** module. Returns `404` if the module is not enabled on your environment.

---

## Base URL

```
https://api.demo.kyriba.com/api/v1/workcap/supplier-service-accesses
```

---

## Endpoints

>  `{uuid}` accepts **UUID only** - not code.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/workcap/supplier-service-accesses` | List service accesses |
| `POST` | `/api/v1/workcap/supplier-service-accesses` | Create a service access |
| `GET` | `/api/v1/workcap/supplier-service-accesses/{uuid}` | Get by UUID |
| `PUT` | `/api/v1/workcap/supplier-service-accesses/{uuid}` | Update by UUID |
| `DELETE` | `/api/v1/workcap/supplier-service-accesses/{uuid}` | Delete by UUID |
| `GET` | `/api/v1/workcap/supplier-service-accesses/documented-fields` | List documented field names |
| `GET` | `/api/v1/workcap/supplier-service-accesses/documented-fields/{field}` | Get valid enum values |

---

## Pagination

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

>  `metadata.total` may be `0` or absent even when results are returned. Use `len(page) < page.limit` as the stop condition rather than `offset >= total`.

---

## Key Fields

| Field | Description |
|---|---|
| `uuid` | System-generated identifier (used in path - UUID only) |
| `buyer` | Buyer company `{ "uuid": "...", "code": "..." }` |
| `thirdParty` | Supplier third party `{ "uuid": "...", "code": "..." }` - **not** `supplier` |
| `ownershipCompany` | Company that owns this record |
| `invoiceInformationAccessDate` | Date from which invoice info access is active (`YYYY-MM-DD`). Can be `null`. |
| `disputeManagementAccessDate` | Date from which dispute management is active. Can be `null`. |
| `earlyPaymentAccessDate` | Date from which early payment is active. Can be `null`. |
| `invoiceDiscountingAccessDate` | Date from which invoice discounting is active. Can be `null`. |
| `invoiceAuctionAccessDate` | Date from which invoice auction is active. Can be `null`. |

---

## Example Requests

**List all service accesses:**
```
GET /api/v1/workcap/supplier-service-accesses?page.limit=100&page.offset=0
```

**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 buyer:**
```
GET /api/v1/workcap/supplier-service-accesses?filter=buyer.code==COMP_FR
```

**Filter by third party:**
```
GET /api/v1/workcap/supplier-service-accesses?filter=thirdParty.code==SUPPLIER_A
```

**Create a service access:**
```http
POST /api/v1/workcap/supplier-service-accesses
Content-Type: application/json

{
  "buyer": { "code": "COMP_FR" },
  "thirdParty": { "code": "SUPPLIER_A" },
  "earlyPaymentAccessDate": "2025-01-01"
}
```

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

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. The `buyer` + `thirdParty` pair must be **unique** - `409` if combination already exists
3. Path parameter is **UUID only** - cannot use code in `/{uuid}` paths
4. Use `thirdParty` - never `supplier`
5. All date fields can be `null` - always handle with a default
6. `metadata.total` may be `0` or absent - use `len(page) < page.limit` as the pagination stop condition
7. `404` = Working Capital module not enabled on this environment

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Created - returns `{ "uuid": "..." }` |
| `400` | Invalid request body |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Not found or Working Capital module not enabled |
| `409` | buyer + thirdParty combination already exists |

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/supplier-service-accesses/supplier-service-accesses.yaml`