# Permission service (gRPC)

The PermissionService provides an interface for checking permissions for a user, where a permission is an action that is performed on a resource.

## Endpoints

### Check permissions

gRPC `/nominal.authorization.permissions.v1.PermissionService/CheckPermissions`

Checks a list of permissions for the calling user and returns results in the same order.

Request: `CheckPermissionsRequest`

`requests` array of [`CheckPermissionRequest`](https://dev.nominal.io/api/grpc/permission-service.md#checkpermissionrequest)
:   ​

    Fields of `CheckPermissionRequest`

    `action` string required
    :   ​

    `resource` string required
    :   Matches `^ri\.[a-z][a-z0-9\-]*\.([a-z0-9][a-z0-9\-]*)?\.[a-z][a-z0-9\-]*\.[a-zA-Z0-9\-\._]+$`.

Response: `CheckPermissionsResponse`

`responses` array of [`CheckPermissionResponse`](https://dev.nominal.io/api/grpc/permission-service.md#checkpermissionresponse)
:   ​

    Fields of `CheckPermissionResponse`

    `is_authorized` boolean
    :   ​

    `requested_permission` [`CheckPermissionRequest`](https://dev.nominal.io/api/grpc/permission-service.md#checkpermissionrequest)
    :   ​

        Fields of `CheckPermissionRequest`

        `action` string
        :   ​

        `resource` string
        :   Matches `^ri\.[a-z][a-z0-9\-]*\.([a-z0-9][a-z0-9\-]*)?\.[a-z][a-z0-9\-]*\.[a-zA-Z0-9\-\._]+$`.

Request

**Python**

```python
import grpc
from nominal.protos.authorization.permissions.v1 import permissions_pb2, permissions_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
permission_service = permissions_pb2_grpc.PermissionServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = permissions_pb2.CheckPermissionsRequest(
    requests=[{"action": "<action>", "resource": "<resource>"}],
)
response = permission_service.CheckPermissions(request, metadata=auth)
print(response)
```

**Go**

```go
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	permissionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/permissions/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	permissionService := permissionsv1.NewPermissionServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &permissionsv1.CheckPermissionsRequest{
		Requests: []*permissionsv1.CheckPermissionRequest{
			{
				Action:   "<action>",
				Resource: "<resource>",
			},
		},
	}
	response, err := permissionService.CheckPermissions(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

Response

```json
{
  "responses": [
    {
      "is_authorized": true,
      "requested_permission": {
        "action": "<action>",
        "resource": "<resource>"
      }
    }
  ]
}
```

## Types

### CheckPermissionRequest

A permission is the declaration of an action that can be performed on a resource.

`action` string required
:   ​

`resource` string required
:   Matches `^ri\.[a-z][a-z0-9\-]*\.([a-z0-9][a-z0-9\-]*)?\.[a-z][a-z0-9\-]*\.[a-zA-Z0-9\-\._]+$`.

### CheckPermissionResponse

`is_authorized` boolean
:   ​

`requested_permission` [`CheckPermissionRequest`](https://dev.nominal.io/api/grpc/permission-service.md#checkpermissionrequest) required
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.