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.
Tasks are in prerelease. To request this feature on your project, open this prepopulated support ticket and add your project ID before submitting.
-
On a worker: inherits the application’s
authorizationsby default, or overrides them — the same as other application properties that can be set in a web or worker instance (such asrelationships,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
authorizationsautomatically. You cannot grant different authorizations to individual crons.
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 athttp://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:
- Your app sends a token request to
http://localhost:8200/oauth2/token. - The proxy returns a bearer token scoped to those declared permissions.
- Your app uses that token to call the Upsun API.
Parameters
| Parameter | Values | Description |
|---|---|---|
type | task, env | The type of resource to access: task — a task defined in your project. env — the environment API. |
resource | Task name | The name of the task. Required when type is task. |
action | operate, view | operate allows triggering and managing a task. view grants read-only access to the environment API. |
Valid combinations
type | action | resource | What it grants |
|---|---|---|---|
task | operate | Task name | Trigger and manage the named task |
env | view | — | Read-only access to the environment API |