# Get the authenticated principal's entitlements

`GET /platform/v1/me/entitlements`

Return the organizations, catalogs, channels and surfaces
the authenticated principal can reach.

Paginated by organization: one item is one organization, with its catalog, channel and
surface subtree nested inside, and `total` counts organizations. Organizations are ordered
by `id`, so paging is stable. Credentials granted on every organization page over all of
them; credentials granted on particular organizations page over those.

`size` accepts up to 1000 here — above the limit of 100 that applies elsewhere
on the API — so a token entitled to many organizations can read the whole tree in one call.

## Request example

```bash
curl --request GET \
  --url 'https://api.eu1.luigisbox.ai/platform/v1/me/entitlements?page=1&size=20' \
  --header 'Authorization: Bearer <access_token>'
```

## Query Parameters

| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `page` | `integer` | No | Page | >= 1 |
| `size` | `integer` | No | Size | >= 1; <= 1000 |

## Responses

| Status | Description | Content |
|---|---|---|
| `200` | Successful Response | application/json: object |
| `401` | Missing or invalid credentials | application/json: object |
| `403` | Authenticated but not permitted | application/json: object |
| `422` | Request validation failed | application/json: object |

### 200

Successful Response

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `items` | `Array<object>` | Yes | Items | — |
| `items[].catalogs` | `Array<object>` | Yes | The organization's catalogs the principal is entitled to. | — |
| `items[].catalogs[].channels` | `Array<object>` | Yes | The catalog's channels the principal is entitled to. | — |
| `items[].catalogs[].channels[].id` | `string` | Yes | Channel identifier, `lbn_` prefixed. | — |
| `items[].catalogs[].channels[].name` | `string` | Yes | Human-readable channel name, e.g. `example.com`. | — |
| `items[].catalogs[].id` | `string` | Yes | Catalog identifier, `lbc_` prefixed. | — |
| `items[].catalogs[].language` | `string` | Yes | The catalog's language, as a locale identifier, e.g. `en_GB`. | — |
| `items[].catalogs[].name` | `string` | Yes | Human-readable catalog name. | — |
| `items[].catalogs[].surfaces` | `Array<object>` | Yes | The catalog's surfaces the principal is entitled to. | — |
| `items[].catalogs[].surfaces[].id` | `string` | Yes | Surface identifier, `lbs_<intent>_<slug>`. | — |
| `items[].catalogs[].surfaces[].slug` | `string` | Yes | Distinguishes surfaces of the same intent within a catalog. | — |
| `items[].catalogs[].surfaces[].surface_kind` | `string` | Yes | The discovery intent this surface serves. | allowed values: search, recommender, collection |
| `items[].id` | `string` | Yes | Organization identifier, `lbo_` prefixed. | — |
| `items[].name` | `string` | Yes | Human-readable organization name. | — |
| `page` | `integer` | Yes | Page | — |
| `size` | `integer` | Yes | Size | — |
| `total` | `integer` | Yes | Total | — |

##### Response example

```json
{
  "items": [
    {
      "catalogs": [
        {
          "channels": [
            {
              "id": "example",
              "name": "example"
            }
          ],
          "id": "example",
          "language": "example",
          "name": "example",
          "surfaces": [
            {
              "id": "example",
              "slug": "example",
              "surface_kind": "search"
            }
          ]
        }
      ],
      "id": "example",
      "name": "example"
    }
  ],
  "page": 1,
  "size": 1,
  "total": 1
}
```

### 401

Missing or invalid credentials

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 403

Authenticated but not permitted

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 422

Request validation failed

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```