Application Roles

The PingOne Authorize {{apiPath}}/v1/environments/{{envID}}/applicationRoles endpoint provides operations to create, read, update, and delete application roles in PingOne.

Application roles data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`description`	String	Optoinal	Mutable	The description of the application role.
`id`	String	N/A	Read-only	The ID of the application role.
`name`	String	Required	Mutable	The name of the application role.

description

String

Optoinal

Mutable

The description of the application role.

id

String

N/A

Read-only

The ID of the application role.

name

String

Required

Mutable

The name of the application role.

Response codes

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.
403	You do not have permissions or are not licensed to make this request.
404	The requested resource was not found.

Application role errors

In addition to the general error codes, application role 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`	`EMPTY_VALUE`, `INVALID_VALUE`, or `OUT_OF_RANGE`	Message: `Validation Error : [<field> <message>]` When and details When: A `POST` or `PUT` request omits `name` or supplies a blank `name` value, or supplies a `name` value longer than 20 characters or containing characters other than Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, and hyphens, or supplies a `description` value that fails validation Details: Describes the failing property, such as `must not be blank` for an omitted or blank `name`, `must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens` for a `name` with disallowed characters, or `size must be between 1 and 20` for a `name` longer than 20 characters, for example `Validation Error : [name must not be blank]`
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` request specifies an application role name already used by another application role in the environment, or a `PUT` request changes the `name` to one that already exists in the environment Details: `A role with this name already exists.` The target is `name`.
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST` request exceeds the environment’s application role limit Details: `Maximum number of application roles per environment reached`
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `GET /applicationRoles/{appRoleID}/users` request provides a `limit` value less than 1 or greater than 1024 Details: `A query string parameter or value is not valid for this request.` The target is `limit`, with `rangeMinimumValue` 1 and `rangeMaximumValue` 1024 in `innerError`.
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `GET /applicationRoles/{appRoleID}/users` request provides a `cursor` value that is not a valid page cursor Details: `A query string parameter or value is not valid for this request.` The target is `cursor`.
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `GET /applicationRoles/{appRoleID}/users` request provides an `expand` value other than `user` Details: `The expand attribute was invalid`. The target is `expand`, with `allowedValues` listing the supported value `user` in `innerError`.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `applicationRoles:create:applicationRole` permission (`POST`), the `applicationRoles:read:applicationRole` permission (`GET`), the `applicationRoles:update:applicationRole` permission (`PUT`), or the `applicationRoles:delete:applicationRole` permission (`DELETE`), or lacks the `applicationRoles:read:applicationRoleAssignment` permission on the `GET` operations that read role assignments (`/users` endpoints) Details: None
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: A `GET` (single role), `PUT`, or `DELETE` request references an application role ID that does not exist, or the user ID referenced by a role-assignment `GET` request does not exist Details: None
500	`UNEXPECTED_ERROR`	None	Message: `There was an unexpected error with the service. Please try again later.` When and details When: Application role creation fails after repeated attempts to generate a unique identifier Details: None

400

INVALID_DATA

EMPTY_VALUE, INVALID_VALUE, or OUT_OF_RANGE

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

When and details

When: A POST or PUT request omits name or supplies a blank name value, or supplies a name value longer than 20 characters or containing characters other than Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, and hyphens, or supplies a description value that fails validation

Details: Describes the failing property, such as must not be blank for an omitted or blank name, must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for a name with disallowed characters, or size must be between 1 and 20 for a name longer than 20 characters, for example Validation Error : [name must not be blank]

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 request specifies an application role name already used by another application role in the environment, or a PUT request changes the name to one that already exists in the environment

Details: A role with this name already exists. The target is name.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST request exceeds the environment’s application role limit

Details: Maximum number of application roles per environment reached

400

REQUEST_FAILED

INVALID_PARAMETER

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

When and details

When: A GET /applicationRoles/{appRoleID}/users request provides a limit value less than 1 or greater than 1024

Details: A query string parameter or value is not valid for this request. The target is limit, with rangeMinimumValue 1 and rangeMaximumValue 1024 in innerError.

400

REQUEST_FAILED

INVALID_PARAMETER

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

When and details

When: A GET /applicationRoles/{appRoleID}/users request provides a cursor value that is not a valid page cursor

Details: A query string parameter or value is not valid for this request. The target is cursor.

400

REQUEST_FAILED

INVALID_PARAMETER

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

When and details

When: A GET /applicationRoles/{appRoleID}/users request provides an expand value other than user

Details: The expand attribute was invalid. The target is expand, with allowedValues listing the supported value user in innerError.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the applicationRoles:create:applicationRole permission (POST), the applicationRoles:read:applicationRole permission (GET), the applicationRoles:update:applicationRole permission (PUT), or the applicationRoles:delete:applicationRole permission (DELETE), or lacks the applicationRoles:read:applicationRoleAssignment permission on the GET operations that read role assignments (/users endpoints)

Details: None

404

NOT_FOUND

None

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

When and details

When: A GET (single role), PUT, or DELETE request references an application role ID that does not exist, or the user ID referenced by a role-assignment GET request does not exist

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: Application role creation fails after repeated attempts to generate a unique identifier

Details: None

PingOne Platform APIs

Application Roles