People - Permissions API

List permissions of a person

List all permissions of a person with the given :id.

GET /people/:id/permissions

Response

Status: 200 OK
[
  {
    "account": {
      "id": "widget",
      "name": "Widget International"
    },
    "roles": [
      "directory_administrator"
    ]
  },
  {
    "account": {
      "name": "Widget Data Center",
      "id": "wdc"
    },
    "roles": [
      "specialist",
      "service_desk_analyst",
      "service_desk_manager",
      "knowledge_manager",
      "problem_manager",
      "change_manager",
      "release_manager",
      "project_manager",
      "service_level_manager",
      "configuration_manager",
      "account_administrator",
      "account_owner"
    ]
  },
  {
    "account": {
      "name": "Widget North America",
      "id": "wna"
    },
    "roles": [
      "account_administrator"
    ]
  },
  {
    "account": {
      "name": "Widget Europe",
      "id": "weu"
    },
    "roles": [
      "account_administrator"
    ]
  }
]

The response contains these fields by default.

List people of account with specific roles

Returns all the person records that are registered in the account and its directory account, provided that these people have at least one of the specified roles.

GET /people?roles=role1,role2,...

Example:

 $ curl -u "api-token:x" -X GET -H "X-ITRP-Account: widget" "https://api.itrp.com/v1/people?roles=directory_administrator,directory_auditor"

Response

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of people.

List people with specific roles of account

Returns all the person records that have at least one of the specified roles of the account.

GET /people/all_with_roles?roles=role1,role2,...

Example:

 $ curl -u "api-token:x" -X GET -H "X-ITRP-Account: wdc" "https://api.itrp.com/v1/people/all_with_roles?roles=specialist,problem_manager"

Response

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of people.

Add roles to a person

Adds the specified roles of the account to a person with a specific ID.

POST /people/:id/permissions/wdc?roles=role1,role2,...

Example:

 $ curl -u "api-token:x" -X POST -H "X-ITRP-Account: widget" "https://api.itrp.com/v1/people/1234/permissions/wdc?roles=specialist,problem_manager"

Response

The response contains these fields by default.

Overwrite the roles of a person

Overwrite the roles that a person with a specific ID has of the account with the specified roles of the account.

PATCH /people/:id/permissions/wdc?roles=role1,role2,...

Example:

 $ curl -u "api-token:x" -X PATCH -H "X-ITRP-Account: widget" "https://api.itrp.com/v1/people/1234/permissions/wdc?roles=problem_manager,change_manager"

Response

The response contains these fields by default.

Revoke roles of a person

Remove the specified roles of the account from a person with a specific ID.

DELETE /people/:id/permissions/wdc?roles=role1,role2,...

Example:

 $ curl -u "api-token:x" -X DELETE -H "X-ITRP-Account: widget" "https://api.itrp.com/v1/people/1234/permissions/wdc?roles=problem_manager,change_manager"

Response

Status: 204 No Content

Revoke all roles of a person

Remove the specified roles of the account from a person with a specific ID.

DELETE /people/:id/permissions/wdc

Example:

 $ curl -u "api-token:x" -X DELETE -H "X-ITRP-Account: widget" "https://api.itrp.com/v1/people/1234/permissions/wdc"

Response

Status: 204 No Content

Fields

account
Required reference to Account — The account for which the person has permissions
roles
Required array of string max(21) — The roles the person has within the account
  • key_contact
  • auditor
  • directory_auditor (for directory accounts only)
  • specialist
  • service_desk_analyst
  • service_desk_manager
  • knowledge_manager
  • problem_manager
  • change_manager
  • release_manager
  • project_manager
  • service_level_manager
  • configuration_manager
  • account_administrator
  • directory_administrator (for directory accounts only)
  • account_owner