PingOne Platform APIs

Gateway Role Assignments

The gateway role assignments service provides functionality to assign role assignments to a gateway so that the gateway can access the PingOne services it needs. Only gateway resources with a type property value of PING_FEDERATE can have assigned built-in roles.

If the actor creating the PING_FEDERATE gateway has the Environment Admin, Identity Data Admin, or both roles in the environment associated with the gateway, then the gateway is given the corresponding role or roles for that environment. Otherwise, the gateway is created without any role assignments.

Use these data models and requests to manage gateway role assignments. For more information, refer to Roles.

Role assignment scopes can be:

  • Organization

  • Environment

  • Population

  • Application

Gateway role assignments data model

Property Type Required Mutable Description

gateway.id

String

Required

Immutable

The UUID for the gateway.

environment.id

String

Required

Immutable

The environment associated with the gateway.

id

String

N/A

Read-only

The gateway role assignment ID.

role.id

String

Required

Immutable

The role ID.

scope.id

String

Required

Immutable

The role assignment scope ID. When this is an application ID, because an application ID is guarenteed 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

Immutable

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

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.

404

The requested resource was not found.

Gateway role assignment errors

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

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 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: Describes the failing property, such as 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 : [scope.id A valid Scope id 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 request assigns a role with a scope.type of GROUP (gateway role assignments support only ORGANIZATION, ENVIRONMENT, POPULATION, and APPLICATION scopes), or assigns a DaVinci role

Details: Group scope is not a valid scope type. or Can not assign DaVinci roles to gateways.

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 assigns a role the gateway 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: the request targets the actor’s own gateway, 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

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

REQUEST_FAILED

INVALID_FILTER or INVALID_PARAMETER

Message: The request could not be completed. One or more validation errors were in the request. for a filter or order rejection from the shared scaffolding handlers, or The request could not be completed. There was an issue processing the request. for a service-level filter rejection

When and details

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

Details: Describes the rejected filter or order, such as <attribute> is not a valid filter attribute., '<value>' is not a valid scope type. Valid scope types are: [ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, GROUP], '<value>' is not a valid type. Valid types are: [DIRECT, INDIRECT], or the order parameter listing the unsupported fields.

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:gatewayRoleAssignments permission (the GET operations), the permissions:update:gatewayRoleAssignments permission (the POST operation), or the permissions:delete:gatewayRoleAssignments permission (the DELETE operation)

Details: None.

404

NOT_FOUND

None

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

When and details

When: The gateway ID in the request URL does not exist in the environment or is not a gateway type that supports role assignments (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: A GET or DELETE request references a role assignment that does not exist, or does not belong to the gateway in the request URL (a mismatch with the gateway in the URL, or an assignment belonging to a non‑gateway actor)

Details: None.