Skip to main content
Use the Identity Management API to automate Poolside user and team membership administration. This is useful when you need to sync membership from an internal directory or from a human resources system. The Identity Management API also handles systems that do not map groups to Poolside teams through System for Cross-domain Identity Management (SCIM).

​
How it fits with SCIM

SCIM provisioning manages user lifecycle events from your identity provider. The Identity Management API lets you manage users and team membership with your own automation against the /poolside/v1 API. Use the Identity Management API when you need to:
  • Find Poolside users and teams by email address or team name
  • Create or update users without SCIM
  • Suspend, restore access for, or delete users without SCIM
  • Add users to a team
  • Remove users from a team
  • Replace a team’s membership with an exact list of users
The Identity Management API does not create teams. Create the Poolside teams you need before you sync membership.

​
Prerequisites

  • You belong to a team with the tenant-admin role.
  • You know the base URL for your Poolside deployment.
  • You have created the Poolside teams that your automation needs to update. See Teams.

​
Set up API access

To create an API key for identity management automation:
  1. In the Poolside Console, navigate to Organization > https://mintcdn.com/poolside/Tz6xG1rOCu6JtFws/images/icons/roles-icon.svg?fit=max&auto=format&n=Tz6xG1rOCu6JtFws&q=85&s=b9f3418edba6807cc9d2d8f4e449b887 Roles.
  2. Create or edit a role that includes the Provision Users with SCIM permission.
  3. In the Poolside Console, navigate to Organization > https://mintcdn.com/poolside/Tz6xG1rOCu6JtFws/images/icons/teams-icon.svg?fit=max&auto=format&n=Tz6xG1rOCu6JtFws&q=85&s=f46ebe329177d0fc8ee734a50c987145 Teams.
  4. Create or edit a team and assign that role to the team.
  5. In the Poolside Console, navigate to Security > https://mintcdn.com/poolside/Tz6xG1rOCu6JtFws/images/icons/key-icon.svg?fit=max&auto=format&n=Tz6xG1rOCu6JtFws&q=85&s=471edb89504a9e747e97caa541181d47 API Keys.
  6. Create a service account API key for that team.
  7. Store the generated API key securely. Poolside shows the full API key value only when you create it.
For more information about API keys, see Authentication and API keys.

​
Sync team membership from a human resources system

To sync a Poolside team’s membership from another system, find the team ID, find the user IDs, and then set the team’s members to the exact list from your source system. The examples in this section use environment variables for the base URL and API key: 
export POOLSIDE_API_BASE="https://<api-domain>"
export POOLSIDE_API_KEY="<api-key>"

​
Find a team

List teams to find the ID of the Poolside team you want to update. You can filter teams by exact name or by name prefix. 
curl --request GET \
  --url "$POOLSIDE_API_BASE/poolside/v1/teams?name_prefix=dep_" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $POOLSIDE_API_KEY"
The response includes team IDs and names: 
{
  "links": {},
  "teams": [
    {
      "id": "<team-id>",
      "name": "dep_engineering"
    }
  ]
}

​
Find users

Use each user’s email address from your source system to find the matching Poolside user ID. Email matching is case-insensitive. 
curl --get \
  --url "$POOLSIDE_API_BASE/poolside/v1/users" \
  --data-urlencode "email=<user-email>" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $POOLSIDE_API_KEY"
The response includes user IDs, email addresses, status, and a first page of team memberships.

​
Replace a team’s membership

Use set when your source system is the source of truth for a Poolside team. This request makes the provided user_ids the exact membership list for the team. Poolside adds users in the list who are not already members and removes team members who are not in the list. 
curl --request POST \
  --url "$POOLSIDE_API_BASE/poolside/v1/teams/<team-id>/members/set" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $POOLSIDE_API_KEY" \
  --data '{
  "user_ids": [
    "<user-id-1>",
    "<user-id-2>"
  ]
}'
The response includes how many memberships Poolside added and removed: 
{
  "added": 2,
  "removed": 0
}

​
Verify team membership

List team members after a sync to confirm the result. 
curl --request GET \
  --url "$POOLSIDE_API_BASE/poolside/v1/teams/<team-id>/members" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $POOLSIDE_API_KEY"

​
Choose a membership update method

EndpointWhen to use itBehavior
POST /poolside/v1/teams/<team-id>/members/setYour source system owns the full membership list for a team.Replaces the team’s membership with the provided user IDs.
POST /poolside/v1/teams/<team-id>/members/addYou need to add users without changing existing members.Adds the provided users. Existing members are not added again.
POST /poolside/v1/teams/<team-id>/members/removeYou need to remove users without changing other members.Removes the provided users. If a provided user ID does not exist, the request returns an error.

​
Provision users without SCIM

You can also use the Identity Management API to manage users when you do not use SCIM.
TaskEndpoint
List usersGET /poolside/v1/users
Get a userGET /poolside/v1/users/<user-id>
Create a userPOST /poolside/v1/users
Update a user’s email, name, or statusPATCH /poolside/v1/users/<user-id>
Delete a userDELETE /poolside/v1/users/<user-id>
List a user’s teamsGET /poolside/v1/users/<user-id>/teams
When you update a user, set status_action to suspend to revoke access temporarily or unsuspend to restore access.

​
Pagination

List endpoints return a links.next value when more results are available. To fetch the next page, make a request to the URL in links.next. You can also use page_size to control the number of items returned per page.