keycloak-scim/authorization_services/topics/service-protection-permission-api-papi.adoc

[[_service_protection_permission_api_papi]]
= Managing Permission Requests

Resource servers using the UMA protocol can use a specific endpoint to manage permission requests. This endpoint provides a UMA-compliant flow for registering permission requests and obtaining a permission ticket.

```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
```

A <<_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:

`A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.`

[NOTE]
_Permission ticket support is limited_.
In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {project_name} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned.

In most cases, you won't need to deal with this endpoint directly. {project_name} provides a <<_enforcer_overview, policy enforcer>> that enables UMA for your
resource server so it can obtain a permission ticket from the authorization server, return this ticket to client application, and enforce authorization decisions based on a final requesting party token (RPT).

The process of obtaining permission tickets from {project_name} is performed by resource servers and not regular client applications,
where permission tickets are obtained when a client tries to access a protected resource without the necessary grants to access the resource. The issuance of
permission tickets is an important aspects when using UMA as it allows resource servers to:

* Abstract from clients the data associated with the resources protected by the resource server
* Register in the {project_name} authorization requests which in turn can be used later in workflows to grant access based on the resource's owner consent
* Decouple resource servers from authorization servers and allow them to protect and manage their resources using different authorization servers

Client wise, a permission ticket has also important aspects that its worthy to highlight:

* Clients don't need to know about how authorization data is associated with protected resources. A permission ticket is completely opaque to clients.
* Clients can have access to resources on different resource servers and protected by different authorization servers

These are just some of the benefits brought by UMA where other aspects of UMA are strongly based on permission tickets, specially regarding
privacy and user controlled access to their resources.