Skip to content
This repository has been archived by the owner on Jan 21, 2022. It is now read-only.

API

Jump to bottom
Jeff Pak edited this page Sep 10, 2018 · 2 revisions

Perm API

Perm's API revolves around the question of who can perform what, where.

Perm answers this question a few ways, depending on what information is available, e.g. it can answer ...

  1. Whether a given actor can perform some action on a resource.
  2. For which resources the actor can perform an action.

In addition, Perm provides administrative functionality to maintain administrative state.

Terminology

Actor

The subject that is granted or denied a permission. It may correspond to either a human or machine user of another system.

Properties
  • id (string): The actor's external identifier, e.g., their OIDC subject identifier
  • namespace (string): A unique identifier for the authentication server responsible for managing the actor's identity, e.g., the OIDC issuer identifier
Notes
  • Perm is not responsible for authentication or maintaining identity state. The client is responsible for determining and validating an actor's identity.

Group

A collection of actors, such as the members of a team, that should all maintain the same subset of roles so that their permissions can easily stay in sync.

Properties
  • id (string): The group's external identifier
Notes
  • Perm is not responsible for maintaining group membership state. The client is responsible for providing the list of groups associated with a particular actor. (This may change in the future.)
  • The group properties are likely to change, e.g., a namespace field may get added

Permission

A description of what action an actor can perform, for which resource.

Properties
  • action (string): The verb describing the restriction, usually tied to a particular resource type, e.g., repository.read
  • resource pattern (string): The particular resource or set of resources to which the restriction applies, e.g., alices-secret or bobs-burgers/*
Notes
  • Perm does not currently support any meaningful interpretation of resource patterns, e.g., wildcards

Role

A collection of permissions that multiple actors and groups may be assigned to. Roles are intended to abstract permission management away from subjects, such that, e.g., permissions may be synchronized more easily across members of a particular team or department.

Properties
  • name (string): A unique name identifying the role

Endpoints

Response Codes

All responses return gRPC status response codes. In particular, you may expect Perm to respond with:

  • 0 OK: The response succeeded
  • 3 INVALID_ARGUMENT: The request contains at least one invalid argument
  • 4 DEADLINE_EXCEEDED: The response took too long
  • 5 NOT_FOUND: The requested resource does not exist or the caller is not permitted to read it
  • 6 ALREADY_EXISTS: The requested resource already exists
  • 7 PERMISSION_DENIED: The caller is authenticated but not permitted to perform the request
  • 16 UNAUTHENTICATED: The request requires authentication but the caller is not identified

CreateRole(CreateRoleRequest) -> (CreateRoleResponse, error)

Create a new role.

CreateRoleRequest
  • name (string): The name of the new role
  • permission ([]Permission): The list of permissionss that members of the role will be allowed to perform
CreateRoleResponse
  • role (Role): The newly created role
Error Modes
  • already exists: A role with the requested name already exists

DeleteRole(DeleteRoleRequest) -> (DeleteRoleResponse, error)

Delete a role.

DeleteRoleRequest
  • name (string): The name of the new role
DeleteRoleResponse

empty body

Error Modes
  • not found: No role with the specified name exists

AssignRole(AssignRoleRequest) -> (AssignRoleResponse, error)

Assign an actor to a role.

AssignRoleRequest
  • actor (Actor): The actor being assigned to the role
  • role_name (string): The name of the role to which the actor should be assigned
AssignRoleResponse

empty body

Error Modes
  • not found: No role with the specified name exists
  • already exists: The actor is already assigned to the role

AssignRoleToGroup(AssignRoleToGroupRequest) -> (AssignRoleToGroupResponse, error)

Assign a group to a role.

AssignRoleToGroupRequest
  • group (Group): The group being assigned to the role
  • role_name (string): The name of the role to which the group should be assigned
AssignRoleToGroupResponse

empty body

Error Modes
  • not found: No role with the specified name exists
  • already exists: The group is already assigned to the role

UnassignRole(UnassignRoleRequest) -> (UnassignRoleResponse, error)

Unassign an actor from a role.

UnassignRoleRequest
  • actor (Actor): The actor being unassigned the role
  • role_name (string): The name of the role from which the actor should be unassigned
UnassignRoleResponse

empty body

Error Modes
  • not found: No role with the specified name exists, or the role exists but the actor is not assigned to it

UnassignRoleFromGroup(UnassignRoleFromGroupRequest) -> (UnassignRoleFromGroupResponse, error)

Unassign a group from a role.

UnassignRoleFromGroupRequest
  • group (Group): The group being unassigned from the role
  • role_name (string): The name of the role from which the group should be unassigned
UnassignRoleFromGroupResponse

empty body

Error Modes
  • not found: No role with the specified name exists, or the role exists but the group is not assigned to it

HasPermission(HasPermissionRequest) -> (HasPermissionResponse, error)

Check whether an actor, given a set of group memberships, has a particular permission.

HasPermissionRequest
  • actor (Actor)
  • action (string)
  • resource (string)
  • groups ([]Group)
HasPermissionResponse
  • has_permission (bool): Whether or not the actor, as a member of the specified groups, is permitted to perform the action on the resource
Notes
  • Perm can only match resources to permission resource patterns exactly, e.g., it cannot determine that /foo/bar matches the glob /foo/*. This may change in the future.

ListResourcePatterns(ListResourcePatternsRequest) -> (ListResourcePatternsResponse, error)

List the resource patterns on which an actor can perform a particular action

ListResourcePatternsRequest
  • actor (Actor)
  • action (string)
  • groups ([]Group)
ListResourcePatternsResponse
  • resource_patterns ([]string)

Usage

Perm's gRPC API may be used directly from the language of your choice, so long as it is supported by gRPC and protocol buffers. You may compile a language-specific client using protoc.

We also currently provide SDKs for the following languages:

Clone this wiki locally