Twilio Segment logo

IAM Groups

A User Group is a set of Team Members with a set of shared policies. A Segment Team Member can be a member of one or many Groups. All roles in the Segment App are additive, which means that you can assign group memberships and individual roles to a single team member. For example, a single user can inherit roles from a Group definition AND have access to more resources through individually assigned roles.

Add Permissions to User Group

Adds a list of access permissions to a user group.

• When called, this endpoint may generate one or more of the following audit trail events:* Policy Created

  • User Group Policy Updated

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Request Body schema:
required
required
Array of objects (permissions)

The permissions to add.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/groups/{userGroupId}/permissions
Request samples
{
  • "permissions": [
    ]
}
Response samples
{
  • "data": {
    }
}

Replace Permissions for User Group

Updates the list of access permissions for a user group.

• When called, this endpoint may generate the Policy Deleted event in the audit trail.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Request Body schema:
required
required
Array of objects (permissions)

The permissions to replace with.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

put/groups/{userGroupId}/permissions
Request samples
{
  • "permissions": [
    ]
}
Response samples
{
  • "data": {
    }
}

Add Users to User Group

Adds a list of users or invites to a user group.

• When called, this endpoint may generate one or more of the following audit trail events:* Subjects Added to Group

  • User Added To User Group

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Request Body schema:
required
emails
required
Array of strings (emails)

The email addresses of the users and invites to add.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/groups/{userGroupId}/users
Request samples
{
  • "emails": [
    ]
}
Response samples
{
  • "data": {
    }
}

List Users from User Group

Returns users belonging to a user group.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
query Parameters
object (PaginationInput)

Pagination for members of a group.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/groups/{userGroupId}/users
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.listUsersFromUserGroup('bBABwqbaDf2QdwTbW8bNEm'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Create User Group

Creates a user group.

• When called, this endpoint may generate one or more of the following audit trail events:* User Group Created

  • Policy Created

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
Request Body schema:
required
name
required
string (name)

The name of the user group to create.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/groups
Request samples
{
  • "name": "New User Group Nbr5tuI40h"
}
Response samples
{
  • "data": {
    }
}

List User Groups

Returns all user groups.

Securitytoken
Request
query Parameters
object (PaginationInput)

Pagination for user groups.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/groups
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.listUserGroups())
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Delete User Group

Removes a user group from a Workspace.

• When called, this endpoint may generate the User Group Deleted event in the audit trail.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: 2c0vZc1kXJ9Nf9wIJ1Gb7JzORGf
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/groups/{userGroupId}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.deleteUserGroup('2c0vZc1kXJ9Nf9wIJ1Gb7JzORGf'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get User Group

Returns a user group.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/groups/{userGroupId}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.getUserGroup('bBABwqbaDf2QdwTbW8bNEm'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update User Group

Updates a user group for a Workspace.

• When called, this endpoint may generate the User Group Updated event in the audit trail.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Request Body schema:
required
name
required
string (name)

The intended value to rename the user group to.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/groups/{userGroupId}
Request samples
{
  • "name": "PAPI Example Group"
}
Response samples
{
  • "data": {
    }
}

List Invites from User Group

Returns the emails of invitees to a user group.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
query Parameters
object (PaginationInput)

Pagination for invites to the group.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/groups/{userGroupId}/invites
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.listInvitesFromUserGroup('bBABwqbaDf2QdwTbW8bNEm'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Remove Users from User Group

Removes one or multiple users or invites from a user group by email.

• When called, this endpoint may generate one or more of the following audit trail events:* Group Memberships Deleted

  • User Removed From User Group

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
query Parameters
emails
required
Array of strings (emails)

The list of emails to remove from the user group.

This parameter exists in v1.

Example: emails=emails.0=foo%40example.com
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/group/{userGroupId}/users
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.iamGroups.removeUsersFromUserGroup('bBABwqbaDf2QdwTbW8bNEm', 'emails.0=foo%40example.com'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Replace Users in User Group

Replaces the members of a user group by email.

• When called, this endpoint may generate one or more of the following audit trail events:* Subjects Added to Group

  • User Added To User Group
  • Group Memberships Deleted

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
userGroupId
required
string [ 1 .. 255 ]
Example: bBABwqbaDf2QdwTbW8bNEm
Request Body schema:
required
emails
required
Array of strings (emails)

The email addresses of the users and invites to replace.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

put/group/{userGroupId}/users
Request samples
{
  • "emails": [
    ]
}
Response samples
{
  • "data": {
    }
}
➔ Next to Labels