# IAM API v3 Migration

This guide will help you migrate to the latest IAM API v3 endpoints.

For the most accurate API description, review our public [OpenAPI](<https://iam.apis.syseleven.de/v3/docs>) spec.

## Removal of /v2/me

We removed the `/me` endpoint, which we designed for internal purposes. If you use this endpoint, get in [contact with our support team](<https://documentation.syseleven.de/en/support/index.md>).

## Changes to HTTP return codes

With the new `/v3` version, we introduced more accurate return codes for POST and DELETE requests.

- The API returns 201 when creating a resource, instead of 200
- The API returns 204 when deleting a resource, instead of 200

## S3 response model changes

```http
GET /v3/orgs/{org_id}/projects/{project_id}/s3-users
```

This endpoint now returns a list of s3-users without associated keys, because the original call became expensive for projects with s3-users that have keys.

If you need the keys for a specific user, make a separate call to:

```http
GET /v3/orgs/{org_id}/projects/{project_id}/s3-users/{user_id}/ec2-credentials
```

## Membership and Permission endpoint changes

### Permissions

In `/v3` we split all permission endpoints by resource and now also return inferred permissions that are not directly set.

For example:

- `/v3/orgs/{org_id}/users/{user_id}/permissions` for users
- `/v3/orgs/{org_id}/service_accounts/{service_account_id}/permissions` for service accounts
- `/v3/orgs/{org_id}/teams/{team_id}/permissions` for teams

These replace the single `/v2/orgs/{org_id}/memberships/{member_id}` endpoint from v2.

Permissions are now set atomically via a PUT request to the specific permission endpoint, for example:

- `PUT /v3/orgs/{org_id}/users/{user_id}/permissions/{permission_name}` with the request body `{"active": true|false}`

Or set all permissions at once:

- `PUT /v3/orgs/{org_id}/users/{user_id}/permissions` with a request body containing the complete list of permissions the user should have, for example `["can_become_project_administrator_in_org", "can_invite_members_in_org", "can_manage_contact_persons_in_org", ...]`

### Memberships

`/v3/orgs/{org_id}/memberships` no longer returns full member objects. Instead, it returns `id`, `type`, and `display_name` directly in the root object.

We omit the Organization object since the API call already uses the `{org_id}`.

All permissions now appear together in a new format that indicates whether each assigned permission is direct or indirect.

The memberships endpoint also supports filtering by membership type through the `principal_type` query parameter (for example `user,service_account,team#member`).

> [!WARNING]
>
> **Differences between membership of users and org resources**
>
> Users are the sole entities removable from an Org, which you remove via:
>
> ```http
> DELETE /v3/orgs/{org_id}/users/{user_id}
> ```
>
> This removes the user from the Org but does not delete the user entirely.
>
> All other org resources require deletion via their respective endpoints, for example:
>
> ```http
> DELETE /v3/orgs/{org_id}/service_accounts/{service_account_id}
> ```
>
> This deletes the resource.

### Members

The new `/members` endpoint is available for `{orgs}`, `{projects}`, `{teams}`, and `{service_accounts}`. It returns a simple member list for the given resource.

You can also filter by membership type via the `principal_type` query parameter.

## Further assistance

If you have questions, [contact our support team](<https://documentation.syseleven.de/en/support/index.md>).
