Skip to content

SysEleven IAM API v3 Migration

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

For the most accurate API description you can always refer to our public OpenAPI spec.

Removal of /v2/me

We've removed the /me endpoint which was build for internal use only. If you're using this endpoint please get in contact with our support team.

Change of http return codes

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

  • 201 is returned if a resource is created, instead of 200
  • 204 is returned if a resource is deleted, instead of 200

S3 response model changes

GET /v3/orgs/{org_id}/projects/{project_id}/s3-users now only returns a list of the s3-users without the associated keys, since the call was extremly expensive if your project had lots of s3-users with keys.

If you need the keys for a specific user you now need to make an extra call to GET /v3/orgs/{org_id}/projects/{project_id}/s3-users/{user_id}/ec2-credentials.

Membership and Permission endpoint changes

Permissions

In /v3 all permission endpoints are split up for each resource and now also return inferred permissions which 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

instead of a single /v2/orgs/{org_id}/membersips/{member_id} endpoint.

Permissions are now either set atomically via a PUT to the specific permission endpoint.

e.g

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

or atomically with a put for all permissions

  • PUT /v3/orgs/{org_id}/users/{user_id}/permissions with the request body of all the permission the user should have e.g ["can_become_project_administrator_in_org", "can_invite_members_in_org", "can_manage_contact_persons_in_org", ...]

Memberships

/v3/orgs/{org_id}/memberships does not return the full member objects anymore. Instead it returns the id, type and display_name in the root object. The Organization object is omitted since the api-call already is done with the {org_id}.

All Permissions are now returned together in a new format, in which the assigned permission can either be direct or indirect.

The memberships endpoint now also supports a filter for the membership type e.g user,service_account,team#member as a query parameter called principal_type

Differences between membership of users and org resources

The User is the only entity that can be removed from an Org and is removed via the endpoint

  • DELETE /v3/orgs/{org_id}/users/{user_id} ← this will only remove the user from the Org

All other resources in an org need to be deleted via their respective deletion endpoints

  • e.g DELETE /v3/orgs/{org_id}/service_accounts/{service_account_id} ← this will delete the resource.

Members

There is a new /members endpoint for {orgs},{projects},{teams},{service_accounts} which returns a simple member list of the specific resource.

This is also filterable for the membership type via the principal_type query parameter

Further assistance

For any assistance or questions, don't hesitate to contact our support team.