Skip to content

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 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.

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

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:

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).

Differences between membership of users and org resources

Users are the sole entities removable from an Org, which you remove via:

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:

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.