Configure app token authentication

An app token is a Boundary resource that enables authentication for machine-to-machine interactions. Boundary returns an app token's token value when you create it. You can use it to authenticate requests to Boundary's API or CLI. An app token has a required expiration time, as well as an optional maximum inactivity time. You can delete an app token or revoke its permissions.

When you create an app token, you provide a permissions value that defines the grants and grant scopes the token has. Permissions follow the same grant string format used for roles. You can pass permissions directly as a JSON array or as a path to a JSON file using the file:// prefix, for example, file://perms.json.

App token grants are intentionally limited in scope. You cannot assign the following grants to an app token:

Write actions (create, revoke, and delete) on the app token resource.
authorize-session action on the target resource.

To better understand Boundary's permissions model, refer to Permissions in Boundary.

Create an app token

Log in to Boundary.
Select the scope in which you want to create the app token.
Select App Tokens, then click New.
Complete the following fields:
- Name: (Optional) An optional name for identification purposes.
- Description: (Optional) An optional description of the app token.
- Time to live (TTL): (Required) Duration of the app token.
- Time to stale (TTS): (Optional) Duration of inactivity after which the app token becomes stale.
- Permissions: (Required) Permissions to set for the app token.
Click Create.
Either copy or download the app token in the pop-up. This is the only time the app token's token value is displayed. You will not have another opportunity to save it.

$ boundary app-tokens create \
  -scope-id $SCOPE_ID \
  -name "example-app-token" \
  -description "An example app token" \
  -time-to-live 30d \
  -permissions file://perms.json

Copy the app token's token value in the response. This is the only time the app token's token value is displayed. You will not have another opportunity to save it.

Refer to the app-tokens create command documentation for more information.

Apply the following Terraform configuration:

resource "boundary_app_token" "appt" {
    # This example assumes that you have stored value of $SCOPE_ID in a Terraform variable
    scope_id              = var.scope_id
    name                  = "example-app-token"
    description           = "An example app token"
    time_to_live_seconds  = 2592000 # 30 days
    permissions           = file("~/perms.json")
}

More information

Refer to the App token domain model topic to learn more about app tokens.
Refer to Permissions in Boundary to learn more about grants and grant scopes.
To learn more about managing app tokens, refer to the CLI app-tokens topic or the API App tokens service topic.