IAM Users

Segment’s access management tools let Workspace owners manage which users can access different parts of their Segment Workspaces.

Add Permissions to User

Adds a list of access permissions to a user.

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

  • User 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
userId
required
string [ 1 .. 255 ]
Example: sgJDWk3K21k6LE3tLU9nRK
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/users/{userId}/permissions
Request samples
{
  • "permissions": [
    ]
}
Response samples
{
  • "data": {
    }
}

Replace Permissions for User

Updates the list of access permissions for a user.

• 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
userId
required
string [ 1 .. 255 ]
Example: sgJDWk3K21k6LE3tLU9nRK
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

put/users/{userId}/permissions
Request samples
{
  • "permissions": [
    ]
}
Response samples
{
  • "data": {
    }
}

Create Invites

Invites a list of users to join a Workspace.

• When called, this endpoint may generate one or more of the following audit trail events:* Non-Segment User Invited to Workspace

  • Policy Created
  • New Segment User Invited to Workspace

Config API omitted fields:

  • parent

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
required
Array of objects (invites)

The list of invites.

Responses
201

Created

404

Resource not found

422

Validation failure

429

Too many requests

post/invites
Request samples
{
  • "invites": [
    ]
}
Response samples
{
  • "data": {
    }
}

Delete Invites

Removes a list of invitations to join a Workspace.

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

  • 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
query Parameters
emails
required
Array of strings (emails)

The list of emails to delete invites for.

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/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.iamUsers.deleteInvites('emails.0=foo%40example.com'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List Invites

Returns a list of invitations to join a Workspace.

Config API omitted fields:

  • parent
Securitytoken
Request
query Parameters
required
object (PaginationInput)

Defines the pagination parameters.

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/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.iamUsers.listInvites('pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Delete Users

Removes one or multiple users.

• When called, this endpoint may generate the Group Memberships 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
query Parameters
userIds
required
Array of strings (userIds)

The ids of the users to remove.

This parameter exists in v1.

Example: userIds=userIds.0=dLPzv57d5nRGz8U5iegLKp
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/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.iamUsers.deleteUsers('userIds.0=dLPzv57d5nRGz8U5iegLKp'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List Users

Returns a list of users with access to the Workspace.

Securitytoken
Request
query Parameters
required
object (PaginationInput)

Pagination for users.

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/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.iamUsers.listUsers('pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get User

Returns a user given their id.

Securitytoken
Request
path Parameters
userId
required
string [ 1 .. 255 ]
Example: sgJDWk3K21k6LE3tLU9nRK
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/users/{userId}
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.iamUsers.getUser('sgJDWk3K21k6LE3tLU9nRK'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List User Groups from User

Returns all groups a user belongs to.

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

Pagination for 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/users/{userId}/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.iamUsers.listUserGroupsFromUser('sgJDWk3K21k6LE3tLU9nRK', 'pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}