Application Role Assignments

The role assignments endpoint implements functions to create, read, and delete the role assignments associated with applications resources. For more information about roles and the permissions associated with each role, refer to Roles.

Role assignments are defined by the role itself, and at a more granular level by the scope attribute associated with the role assignment. The role assignment scope identifies the type of platform resource that defines the scope, and the id of the specific resource to which the scope applies. The following sample shows the scope attribute, which includes the resource type and id attributes. In this case, the scope is restricted to the environment resource identified by its id.

{
  "scope": {
   "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
   "type": "ENVIRONMENT"
   }
}

Role assignment scopes can be:

Organization
Environment
Population
Application

Applications role assignments data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`application.id`	String	Required	Read only	The application resource ID associated with the role assignment.
`environment.id`	String	Required	Read only	The environment associated with the application role assignment.
`id`	String	Required	Read only	The application role assignment ID.
`readOnly`	Boolean	Optional	Mutable	Indicates whether this role assignment can be deleted by the current actor. Varies depending on the actor accessing the role assignment and is only `true` under the following conditions: The actor is the target, or the actor does not have the role (or a role that can assign the role) for the scope or an ancestor of the scope.
`role.id`	String	Required	Mutable	The role ID.
`scope.id`	String	Required	Mutable	The role assignment scope ID. When this is an application ID, because an application ID is guaranteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.
`scope.type`	String	Required	Mutable	The type of resource defining the scope of the Role assignment. Options are `ORGANIZATION`, `ENVIRONMENT`, `POPULATION`, `APPLICATION`.

application.id

String

Required

Read only

The application resource ID associated with the role assignment.

environment.id

String

Required

Read only

The environment associated with the application role assignment.

id

String

Required

Read only

The application role assignment ID.

readOnly

Boolean

Optional

Mutable

Indicates whether this role assignment can be deleted by the current actor. Varies depending on the actor accessing the role assignment and is only true under the following conditions: The actor is the target, or the actor does not have the role (or a role that can assign the role) for the scope or an ancestor of the scope.

role.id

String

Required

Mutable

The role ID.

scope.id

String

Required

Mutable

The role assignment scope ID. When this is an application ID, because an application ID is guaranteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.

scope.type

String

Required

Mutable

The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION.

Response codes

The /v1/environments/{{envID}}/applications/{{appID}}/roleAssignments endpoint returns a 404 NOT FOUND on GET, POST, PUT, and DELETE operations if the application’s type property is not set to WORKER.

Code	Message
200	Successful operation.
201	Successfully created.
204	Successfully removed. No content.
400	The request could not be completed.
401	You do not have access to this resource.
404	The requested resource was not found.

Application role assignment errors

In addition to the general error codes, application role assignment operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST /roleAssignments` request body omits `role`, `role.id`, `scope.id`, `scope.type`, or `environment.id`, supplies a `scope.id` that is not a UUID, assigns a role that does not exist in the environment, or assigns a role that does not support the requested scope type Details: `A valid Role is required` for an omitted `role` or `role.id`, `A valid Scope id is required` for an omitted `scope.id`, `A valid Scope type is required` for an omitted `scope.type`, `A valid Environment is required` for an omitted `environment` or `environment.id`, `Scope id is not a valid UUID.` for a `scope.id` that is not a UUID, `Role with such UUID does not exist.` for a role that does not exist in the environment, or `Provided scope is not applicable to role.` for a role that does not support the requested scope type, for example `Validation Error : [role A valid Role is required]`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /roleAssignments` request assigns a role with a `scope.type` of `GROUP` (application role assignments support only `ORGANIZATION`, `ENVIRONMENT`, `POPULATION`, and `APPLICATION` scopes) Details: `Group scope is not a valid scope type.`
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /roleAssignments` request assigns a role the application already has at the same scope or at a scope that contains or is contained by the requested scope Details: `May not assign duplicate Role`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: The actor is not allowed to assign the role, or to remove it on `DELETE /roleAssignments/{ID}`: the request targets the actor’s own application, the actor does not have the role at the same or a broader scope, a custom role is scoped outside the environment it belongs to, or the requested scope is outside the actor’s organization Details: Describes the failed privilege check, such as `May not change role assignments for self`, `Must have role at the same or broader scope`, `May only scope custom roles for environment they live in`, or `May not assign roles for scopes outside the organization`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: The access token does not contain the claims needed to identify the actor Details: `Can not determine actor from claims`
400	`REQUEST_FAILED`	None	Message: `Limit exceeded for role assignments per actor. Limit is <maximum>` When and details When: A `POST /roleAssignments` request would exceed the maximum number of role assignments for the application Details: None.
400	`REQUEST_FAILED`	None	Message: `Limit exceeded for role assignments with <scopeType> scope type per client. Limit is <maximum>` When and details When: A `POST /roleAssignments` request with a `POPULATION` or `APPLICATION` scope type would exceed the maximum number of role assignments of that scope type for the application Details: None.
400	`INVALID_REQUEST`	None	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A path identifier cannot be parsed as a UUID Details: None.
400	`INVALID_REQUEST`	`INVALID_VALUE` or None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A `POST /roleAssignments` request body cannot be deserialized Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.
400	`REQUEST_FAILED`	`INVALID_FILTER` or `INVALID_PARAMETER`	Message: `The request could not be completed. One or more validation errors were in the request` or `The request could not be completed. There was an issue processing the request.` When and details When: `GET /roleAssignments` uses an unsupported or malformed `filter` or `order` query parameter Details: Describes the rejected filter or order.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `permissions:read:applicationRoleAssignments` permission (`GET` operations) or the `permissions:update:applicationRoleAssignments` permission (`POST` and `DELETE` operations) Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: The application ID in the request URL does not exist in the environment or is not a WORKER application (applies to all operations) Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: `GET` or `DELETE /roleAssignments/{ID}` references a role assignment that does not exist, does not belong to the application in the request URL, or is not an application role assignment Details: None.

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /roleAssignments request body omits role, role.id, scope.id, scope.type, or environment.id, supplies a scope.id that is not a UUID, assigns a role that does not exist in the environment, or assigns a role that does not support the requested scope type

Details: A valid Role is required for an omitted role or role.id, A valid Scope id is required for an omitted scope.id, A valid Scope type is required for an omitted scope.type, A valid Environment is required for an omitted environment or environment.id, Scope id is not a valid UUID. for a scope.id that is not a UUID, Role with such UUID does not exist. for a role that does not exist in the environment, or Provided scope is not applicable to role. for a role that does not support the requested scope type, for example Validation Error : [role A valid Role is required]

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /roleAssignments request assigns a role with a scope.type of GROUP (application role assignments support only ORGANIZATION, ENVIRONMENT, POPULATION, and APPLICATION scopes)

Details: Group scope is not a valid scope type.

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /roleAssignments request assigns a role the application already has at the same scope or at a scope that contains or is contained by the requested scope

Details: May not assign duplicate Role

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: The actor is not allowed to assign the role, or to remove it on DELETE /roleAssignments/{ID}: the request targets the actor’s own application, the actor does not have the role at the same or a broader scope, a custom role is scoped outside the environment it belongs to, or the requested scope is outside the actor’s organization

Details: Describes the failed privilege check, such as May not change role assignments for self, Must have role at the same or broader scope, May only scope custom roles for environment they live in, or May not assign roles for scopes outside the organization

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: The access token does not contain the claims needed to identify the actor

Details: Can not determine actor from claims

400

REQUEST_FAILED

None

Message: Limit exceeded for role assignments per actor. Limit is <maximum>

When and details

When: A POST /roleAssignments request would exceed the maximum number of role assignments for the application

Details: None.

400

REQUEST_FAILED

None

Message: Limit exceeded for role assignments with <scopeType> scope type per client. Limit is <maximum>

When and details

When: A POST /roleAssignments request with a POPULATION or APPLICATION scope type would exceed the maximum number of role assignments of that scope type for the application

Details: None.

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST /roleAssignments request body cannot be deserialized

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

400

REQUEST_FAILED

INVALID_FILTER or INVALID_PARAMETER

Message: The request could not be completed. One or more validation errors were in the request or The request could not be completed. There was an issue processing the request.

When and details

When: GET /roleAssignments uses an unsupported or malformed filter or order query parameter

Details: Describes the rejected filter or order.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permissions:read:applicationRoleAssignments permission (GET operations) or the permissions:update:applicationRoleAssignments permission (POST and DELETE operations)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The application ID in the request URL does not exist in the environment or is not a WORKER application (applies to all operations)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET or DELETE /roleAssignments/{ID} references a role assignment that does not exist, does not belong to the application in the request URL, or is not an application role assignment

Details: None.

PingOne Platform APIs

Application Role Assignments

Applications role assignments data model

Response codes

Application role assignment errors