Skip to main content
Upsun runs several types of workloads — applications, workers, crons, and tasks. The authorizations key enables a workload to call the Upsun API at runtime using short-lived, narrowly-scoped tokens, with no long-lived credentials required. This key can be declared on both applications and tasks, but serves a different purpose depending on where it’s declared:
  • On an application: grants permission to trigger tasks and call the environment API.
  • On a task: grants the task permission to call the environment API from inside its container. A task can also trigger another task.
  • On a worker: inherits the application’s authorizations by default, or overrides them — the same as other application properties that can be set in a web or worker instance (such as relationships, mounts; for a complete list, refer to the Set in instance column of the Primary applicaton properties table in the single-runtime and composable image topics).
  • On a cron: crons run inside the application container and inherit its authorizations automatically. You cannot grant different authorizations to individual crons.
The authorizations key grants an application or task permission to make specific calls to the Upsun API from inside its container. Each authorization defines a type and an action, and optionally a resource to scope the permission. No user API token or long-lived credential is required. The platform injects a short-lived bearer token at runtime, scoped to the permissions declared here.

​
How it works

Instead of storing a long-lived API token in your environment, every application and task container has a local auth proxy running at http://localhost:8200. The proxy issues short-lived tokens scoped to the permissions you declared — so there are no credentials to rotate, and a token issued in one environment cannot act on another. When your code needs to call the Upsun API:
  1. Your app sends a token request to http://localhost:8200/oauth2/token.
  2. The proxy returns a bearer token scoped to those declared permissions.
  3. Your app uses that token to call the Upsun API.

​
Parameters

​
Valid combinations

​
Examples

Allow an application to trigger a task and read the environment API: Allow a task to read the environment API:
Last modified on August 12, 2026