# List permissions

Source: https://api-docs.magicdoor.com/api-reference/permissions/list-permissions

Returns every permission a property manager can be granted, with a human-readable name, description, and category. Use it to build a permission picker or to look up the exact strings to send when creating an API key.

`GET https://auth.magicdoor.com/company-portal/permissions`

**Authentication:** bearer token in the `Authorization` header, as `Bearer <token>`.

## Query parameters

- `category` (string) — Return only permissions whose `category` matches this exactly, spelling and capitalisation included. Take the value from a `category` in an unfiltered response. Example: `Leases`.
- `search` (string) — Return only permissions whose `name` or `description` contains this text, ignoring case. It does not search `code`. Example: `lease`.

## Example request

```bash
curl --request GET \
  --url 'https://auth.magicdoor.com/company-portal/permissions?category=Leases&search=lease' \
  --header 'Authorization: Bearer <token>'
```

## Responses

### 200 — Every matching permission. Not paged — the whole list comes back at once

- `code` (string) — The `resource:action` string to send in an API key's `permissions` list.
- `name` (string) — A short label for a picker, for example *Read Leases*.
- `description` (string) — A sentence saying what holding this permission lets someone do.
- `category` (string) — The resource this permission belongs to, for grouping a picker. Also the value the `category` filter matches.
- `portal` (string) — Which portal the permission belongs to. Always `CompanyPortal` here.

```json
[
  {
    "code": "leases:read",
    "name": "Read Leases",
    "description": "View lease details, list leases, search leases.",
    "category": "Leases",
    "portal": "CompanyPortal"
  },
  {
    "code": "leases:write",
    "name": "Write Leases",
    "description": "Create new leases, update existing leases, modify lease terms.",
    "category": "Leases",
    "portal": "CompanyPortal"
  },
  {
    "code": "api_keys:read",
    "name": "Read Api Keys",
    "description": "View the company's API keys and when they were last used. Never exposes a key's secret.",
    "category": "Api Keys",
    "portal": "CompanyPortal"
  }
]
```

### 401 — The access token is missing, expired, or invalid

This is a fixed catalogue of names and descriptions with no company or user data in it, so it needs no permission of its own — any signed-in property manager can read it. It is also scoped by the route: only permissions a property manager can hold are reachable here, never a tenant's, an owner's, a vendor's, or MagicDoor's internal ones.

> **Note: What you can see is not what you can grant**
>
> The list is the same for everyone. It is not narrowed to what the caller holds, so it will show permissions you cannot grant. Asking for one of those when [creating an API key](https://api-docs.magicdoor.com/api-reference/api-keys/create-api-key.md) returns `403`, naming the ones at fault.