# List authorizations

> The authorizations.list operation: GET /api/v1/authorizations in the REST API and the authorizations_list tool in the MCP server.

Lists who may act for the legal entity with tax authorities in the mode of the request, newest first: the
holder (a person, a firm or an installed app), the kind of authority, the regimes and portals it covers, its
validity and document. `status` is as of now (`expired` once past `validTo`). Filter by `regimeId`, or
`validNow: true` for the ones a submission can reference now.

## At a glance

- **REST:** `GET /api/v1/authorizations`
- **MCP tool:** `authorizations_list`
- **Operation ID:** `authorizations.list`
- **Scope:** Legal entity
- **Permission:** `tasks:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `tasks:read` scope
- **Since:** M10

## Request

### Query parameters

| Field            | Type               | Required | Description |
| ---------------- | ------------------ | -------- | ----------- |
| `limit`          | integer (1 to 100) | No       |             |
| `starting_after` | `atz_…` ID         | No       |             |
| `regimeId`       | string             | No       |             |
| `validNow`       | boolean or string  | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                             | Type                                                                                                   | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------- |
| `object`                          | `"list"`                                                                                               |             |
| `data`                            | array of object                                                                                        |             |
| `data[].id`                       | `atz_…` ID                                                                                             |             |
| `data[].object`                   | `"authorization"`                                                                                      |             |
| `data[].entityId`                 | `ent_…` ID                                                                                             |             |
| `data[].livemode`                 | boolean                                                                                                |             |
| `data[].regimeIds`                | array of string                                                                                        |             |
| `data[].holder`                   | object                                                                                                 |             |
| `data[].holder.type`              | one of `person`, `firm`, `app`                                                                         |             |
| `data[].holder.name`              | string                                                                                                 |             |
| `data[].holder.contact`           | string or null                                                                                         |             |
| `data[].holder.appInstallationId` | `ains_…` ID or null                                                                                    |             |
| `data[].kind`                     | one of `employee_eid`, `power_of_attorney`, `tax_representative`, `fiscal_representative`, `api_oauth` |             |
| `data[].documentFileId`           | `file_…` ID or null                                                                                    |             |
| `data[].validFrom`                | date-time                                                                                              |             |
| `data[].validTo`                  | date-time or null                                                                                      |             |
| `data[].portals`                  | array of string                                                                                        |             |
| `data[].accessNotes`              | object or null                                                                                         |             |
| `data[].status`                   | one of `active`, `expired`, `revoked`, `not_yet_valid`                                                 |             |
| `data[].revokedAt`                | date-time or null                                                                                      |             |
| `data[].revocationReason`         | string or null                                                                                         |             |
| `data[].createdAt`                | date-time                                                                                              |             |
| `data[].updatedAt`                | date-time                                                                                              |             |
| `data[].version`                  | integer (at least 1)                                                                                   |             |
| `has_more`                        | boolean                                                                                                |             |
| `next_cursor`                     | `atz_…` ID or null                                                                                     |             |

## Examples

### Who may file the OSS return now

```http
GET /api/v1/authorizations?regimeId=EU_OSS_UNION&validNow=true
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "atz_01m4ttwd3veh9apbewxheq5xa3",
      "object": "authorization",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "livemode": true,
      "regimeIds": ["EU_OSS_UNION"],
      "holder": {
        "type": "person",
        "name": "Ana Horvat",
        "contact": "ana.horvat@example.com",
        "appInstallationId": null
      },
      "kind": "employee_eid",
      "documentFileId": null,
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validTo": "2027-12-31T23:00:00.000Z",
      "portals": ["Croatian Tax Administration OSS portal (ePorezna)"],
      "accessNotes": {
        "method": "eid",
        "renewalDueAt": "2027-11-30T23:00:00.000Z",
        "notes": "Ana signs in with her personal eID card."
      },
      "status": "active",
      "revokedAt": null,
      "revocationReason": null,
      "createdAt": "2026-01-05T10:00:00.000Z",
      "updatedAt": "2026-01-05T10:00:00.000Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                  | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or pagination value is invalid.              | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)       | 400         | The request names no legal entity.                    | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't see this entity's tasks and authorizations. | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).