---
name: data-permissions-profiles
description: >
  Instructs AI agents how to query Data Permission Profiles in Kyriba.
  Profiles bundle data permission rules and are applied to companies or
  user groups to control entity-level data access.
version: 1.0.0
scopes:
  - data-permission-profile-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - data-permissions
  - 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: Data Permission Profiles

>  **Different from Data Permissions.** The Data Permissions API manages individual rules. This API manages named **profiles** that bundle those rules.

---

## Required Kyriba Permission

```
data-permission-profile-scope
```

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

>  Singular - `data-permission-profile-scope`, no trailing `s`.

---

## Base URL

```
https://api.demo.kyriba.com/api/v1/data-permission-profiles
```

---

##  Non-Standard Path Syntax

Several endpoints embed `dataType` **inline in the path segment** - not as a query parameter:

```
GET /api/v1/data-permission-profiles/dataType=COMPANY
GET /api/v1/data-permission-profiles/{ref}/entities/dataType=COMPANY
```

---

## Endpoints

> Read-only - no POST, PUT, or DELETE.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/data-permission-profiles` | List all profiles |
| `GET` | `/api/v1/data-permission-profiles/dataType={dataType}` | List profiles by dataType |
| `GET` | `/api/v1/data-permission-profiles/{ref}/entities/dataType={dataType}` | List entities in a profile |
| `GET` | `/api/v1/data-permission-profiles/{ref}/permissions` | List permission rules of a profile |

### `dataType` values: `COMPANY` or `USER_GROUP`

---

## Pagination

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

###  Non-Standard Response Metadata

The list response uses non-standard metadata field names:

```json
{
  "metadata": {
    "numberOfTotalResults": 17,
    "pageResults": 17,
    "pageLimit": 100,
    "pageOffset": 0,
    "links": { "current": "..." }
  },
  "results": [ ... ]
}
```

| Standard name | Actual field name |
|---|---|
| `total` | `numberOfTotalResults` |
| `count` | `pageResults` |
| `limit` | `pageLimit` |
| `offset` | `pageOffset` |

---

## Key Fields - List response (`results[]`)

| Field | Description |
|---|---|
| `uuid` | Profile UUID |
| `code` | Profile code |
| `description` | Human-readable label. **Can be `null`**. |
| `companyOwnership` | Owning company `{ "uuid": "...", "code": "..." }`. **Can be `null`**. |

---

## Key Fields - Permissions (`/{ref}/permissions`)

>  Returns a **plain JSON array** - not `{ "results": [...] }`.

```json
[
  {
    "uuid": "...",
    "code": "SUPPLIER01",
    "dataType": null,
    "type": "GENERAL",
    "subtype": "ALL",
    "function": null
  }
]
```

| Field | Description |
|---|---|
| `uuid` | Permission rule UUID |
| `code` | Rule code |
| `dataType` | Restricted data type. Can be `null` (unrestricted). |
| `type` | e.g. `GENERAL` |
| `subtype` | e.g. `ALL` |
| `function` | Specific function restriction. Can be `null`. |

---

## Example Requests

**List all profiles:**
```
GET /api/v1/data-permission-profiles?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`.

**List company profiles:**
```
GET /api/v1/data-permission-profiles/dataType=COMPANY
```

**List entities in a profile:**
```
GET /api/v1/data-permission-profiles/PROFILE_EU/entities/dataType=COMPANY
```

**List permissions of a profile:**
```
GET /api/v1/data-permission-profiles/PROFILE_EU/permissions
```

---

##  Common Mistakes

| Wrong | Correct |
|---|---|
| `?dataType=COMPANY` (query param) | `/dataType=COMPANY` (path segment) |
| Scope `data-permission-profiles-scope` | `data-permission-profile-scope` (no `s`) |
| `response.results` for permissions | Permissions response is a **plain array** - iterate directly |
| Metadata key `total` | `numberOfTotalResults` |

---

## Critical Rules

1. `dataType` is a **path segment** - never a query parameter
2. `{ref}` accepts `uuid` or `code`
3. `/{ref}/permissions` returns a **plain array**, not a paginated object
4. `description` and `companyOwnership` can be `null`
5. Read-only - all management is UI-only

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Profile not found |

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/data-permissions-profiles/data-permissions-profiles.yaml`