--- layout: docs page_title: Permission grant formats description: >- Learn how to construct grant strings that map resources and permissions. Understand ID, Type, Pinned, and Wildcard grant formats. View possible grant templates. --- # Permission grant formats Each grant string is a mapping that describes a resource or set of resources and the permissions that should be granted on them. Refer to [Assignable permissons](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can include in grants. A grant string has a form similar to: `ids=;type=;actions=;output_fields=` There are two types of selectors: - An `id` field that indicates a specific resource or a wildcard to match all - A `type` field that indicates a specific resource type or a wildcard to match all; this might also be used to grant permissions on collections of resources Selectors are used to indicate the resources on which the grant should apply, using specific IDs or wildcard IDs and type selectors. You can supply grant strings using a human-friendly string syntax or using JSON. The following examples use the canonical string syntax. The JSON equivalents are an object with a string `id` value, a string `type` value, a string array `actions` value, and a string array `output_fields` value. In the following examples, `output_fields` is omitted for brevity, but they are valid for each example. It is also valid to omit `actions` and specify only `output_fields`. ## ID only The simplest form of grant allows the specified actions for a given resource. Refer to the following example: `ids=hsst_1234567890;actions=read,update` This example grants `read` and `update` actions to the resource `hsst_1234567890`. It is invalid to specify `create` or `list` as actions in this format, because this format explicitly identifies a resource. The `create` and `list` actions are only supported for collections. ## Type only You can configure a grant to allow the specified actions for a given type. Refer to the following example: `type=host-catalog;actions=create,list` Because type specifies only a collection as opposed to specific resources within that collection, only collection actions are allowed in this format. Currently, this includes the `create` and `list` actions. There is one additional restriction: this grant format is only valid against "top-level" resource types, which include: - Auth methods - Auth tokens - Groups - Host catalogs - Roles - Scopes - Sessions - Targets - Users The reason for this is that other types of resources are contained within one of these resource types. For example, accounts are instantiated within an auth method. To specify actions against an auth method, you must also specify the specific containing resource you want to apply the grants to. You can update those resources using the pinned format shown below. ## Pinned ID This form "pins" actions to a non-top-level type within a specific ID. Refer to the following example: `ids=hcst_1234567890;type=host-set;actions=create,read,update` In this example, the user is able to create, read, or update host sets within the scope, but only the host sets belonging to host catalog `hcst_1234567890`. Pinning is essentially a way to use top-level resources to create mini permission boundaries for their subordinate resources. ## Wildcards You can use wildcards in grants. Refer to the following sections for the various wildcard possibilities that are supported. ### Wildcard ID When just the ID is `*`, it matches all IDs of the given type. You can use this grant format with both top-level resource types and non-top-level resource types. Refer to the following example: `ids=*;type=host-set;actions=create,read,update,set-hosts` ### Wildcard type For non-top-level resources with pinned IDs, the `type` can be a wildcard. Refer to the following example: `ids=hcst_1234567890;type=*;actions=create,read,update` This grant format would allow `create`, `read`, and `update` actions for all types of subordinate resources underneath the host catalog with ID `hcst_1234567890`. In this example, that would include host sets and hosts. ### Wildcard ID and type If the ID and type are both wildcards, the grant is essentially a catch-all that matches any resource of any type within the scope and allows the given actions. Refer to the following example: `ids=*;type=*;actions=read,list` ### Wildcard ID, type, and actions ID, type, and actions can all be wildcards. Refer to the following example: `ids=*;type=*;actions=*` Such a grant is essentially a full administrator grant for a scope. ## Templates A few template possibilities exist for grants. The following templates substitute a given value into the ID field of the grant string at evaluation time: - `{{.Account.Id}}`: The substituted value is the account ID associated with the token used to perform the action. As an example, `ids={{.Account.Id}};actions=read,change-password"` is one of Boundary's default grants to allow users that have authenticated with the Password auth method to change their own password. - `{{.User.Id}}`: The substituted value is the user ID associated with the token used to perform the action. ## More information 1. Refer to [Assignable permissions](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can assign to Boundary principals. 1. Refer to the [Resource table](/boundary/docs/configuration/identity-access-management/resource-table) for a cheat sheet to help you manage your permissions. ## Next steps Refer to [Manage roles and permissions](/boundary/docs/common-workflows/manage-roles) for instructions to configure roles and grant scopes for principals.