Scopes
Every scope the Gigadrive Network API recognises, what each one permits, and what happens when a token is missing one.
A scope is one permission over one kind of resource, written product:resource:action. A token carries the scopes of the API key it came from, and an endpoint refuses the call when none of them satisfies what it requires.
Every scope
| Scope | Permits |
|---|---|
platform:organizations:read | Read organizations, their members, and their product access |
platform:organizations:write | Create an organization |
platform:organizations:delete | Nothing today. Recognised, but no endpoint requires it |
platform:api_keys:read | List an application's API keys |
platform:api_keys:write | Create an application-scoped API key |
platform:api_keys:delete | Revoke an API key |
network:applications:read | List applications, list their hostnames, check hostname availability |
network:applications:write | Create an application, set its production hostname |
network:applications:delete | Nothing today. Recognised, but no endpoint requires it |
network:deployments:read | Read a deployment, its build logs, its log stream and its hostnames, and list deployments |
network:deployments:write | Upload a deployment archive: start the upload, get a part URL, complete it |
network:deployments:trigger | Create a deployment |
network:deployments:delete | Nothing today. Recognised, but no endpoint requires it |
network:env_vars:read | List organization and application environment variables, and pull resolved values |
network:env_vars:write | Create or update an environment variable at either scope |
network:env_vars:delete | Delete an environment variable at either scope |
network:storage_buckets:read | List buckets and read one bucket's metadata |
network:storage_buckets:write | Create a bucket |
network:storage_buckets:delete | Delete an empty bucket |
network:storage_objects:read | List and read objects, upload sessions and trash, and mint an object access URL |
network:storage_objects:write | Create an upload session, restore a trashed object |
network:storage_objects:delete | Trash an object, purge one, empty the trash |
network:storage_s3_credentials:read | List S3-compatible credentials |
network:storage_s3_credentials:write | Create an S3-compatible credential |
network:storage_s3_credentials:delete | Revoke an S3-compatible credential |
network:requests:read | Read request logs and open the application activity stream |
network:sticky_sessions:write | Mint a routing-only sticky URL from a deployed Function |
network:image_optimization:read | Read the managed image cache status and policy for a deployment |
network:image_optimization:purge | Purge the managed image cache for a deployment |
network:runtime_cache:read | Read entries from a Function's private runtime cache |
network:runtime_cache:write | Write entries to a Function's private runtime cache |
network:runtime_cache:revalidate | Invalidate runtime cache tags |
network:ai_gateway:chat | Send AI Gateway inference requests: chat, responses, audio, video |
network:ai_gateway:models | List AI Gateway models |
network:ai_gateway:usage:read | Read organization AI Gateway usage summaries and request logs |
network:ai_gateway:budgets:read | Read organization AI Gateway budgets |
network:ai_gateway:budgets:write | Replace organization AI Gateway budgets |
network:ai_gateway:policies:read | Read organization AI Gateway model and provider policies |
network:ai_gateway:policies:write | Create or update organization AI Gateway model and provider policies |
The three marked as permitting nothing are recognised and can be granted to a key, but no endpoint checks one today. Granting it buys no access.
The interactive reference lists fewer scopes than this
The OAuth scope pickers in the OpenAPI document advertise only the storage bucket, storage object, AI Gateway and sticky-session scopes. Every listed scope is enforced, whether or not the picker offers it.
Scopes a Function receives
A Function does not use a key you created. Gigadrive Network mints one per deployed Function and injects it, with a fixed set of seven scopes: network:sticky_sessions:write, the three network:runtime_cache:* scopes, and read, write and delete on network:storage_objects. It cannot list applications, trigger deployments, read environment variables through the API, or reach any platform: resource. OIDC federation covers what that credential is and how it reaches your code.
The older, un-namespaced names
Scopes used to carry no product prefix: applications:read, deployments:trigger, env_vars:write. Those names are still accepted and are normalised before comparison, so a key holding applications:read satisfies an endpoint requiring network:applications:read and the reverse also holds. Write the canonical form on anything new.
Every legacy alias maps one-to-one onto a canonical scope, with the prefix added: organizations:* and api_keys:* become platform:, everything else becomes network:. Three families arrived after that migration and exist only in canonical form: network:sticky_sessions:write, both network:image_optimization:* scopes, and all three network:runtime_cache:* scopes.
Identity scopes
openid, profile, email and offline_access come from OpenID Connect and concern account information rather than Gigadrive Network resources. A token from /oauth2/token always carries openid, added by the token endpoint whether or not the key lists it. The other three belong to user sign-in through the Gigadrive account system and grant nothing on the Gigadrive Network API.
Choosing what to grant
A key you mint can only carry scopes you already hold, and can never carry platform:api_keys:*. Omit scopes entirely and you get network:env_vars:read alone, which is the right answer for a local development credential. Authentication covers the full set of rules the create call enforces.
Grant per job. A pipeline that ships code needs network:deployments:trigger and network:deployments:write and nothing else; a dashboard reading traffic needs network:requests:read on its own.
When a scope is missing
The check runs before any database lookup and returns 403:
{
"error": "Insufficient scope: This operation requires the 'network:env_vars:write' scope"
}Scope is only half the check. An endpoint that touches one application, deployment or organization also verifies your actor may reach it, and that runs after the scope test. So holding network:deployments:read does not let a key bound to one application read another application's deployments. Errors explains why that second failure sometimes arrives as a 404 rather than a 403.