Skip to content

Using OIDC Scopes ​

Third-party apps can call the HydroServer Data Management API and SensorThings API on a user's behalf with an OIDC access token. The scopes an app requests decide which endpoints that token can reach. Request only the scopes your app needs: each one appears on the consent screen the user approves.

An administrator must register your app as an OIDC client and allow each scope it requests. See Registering OIDC Clients. Scopes a client isn't allowed are silently dropped from its tokens.

Scopes ​

ScopeGrantsConsent screen
data:readGET on monitoring sites, datastreams, observations, metadata vocabularies (methods, units, processing levels, observed properties, result qualifiers, and system types), quality control histories, and the SensorThings APIView your monitoring sites, datastreams, observations, and quality control history
data:writePOST, PATCH, PUT, and DELETE on the same resourcesCreate, change, and delete your monitoring sites, datastreams, observations, and quality control edits
workspace:readGET /api/ogc/collections/workspaces/items and GET /api/ogc/collections/workspaces/items/{workspace_id}, including owner and pending transfer detailsSee your workspaces, including owner and pending transfer details
workspace:writeCreate, update, and delete workspaces, including changing whether a workspace is privateCreate, rename, and delete workspaces, and change their privacy, including making a workspace public
iam:readGET on collaborators, service accounts, and rolesSee who can access your workspaces: collaborators, roles, and service accounts
iam:writeAdd, edit, and remove collaborators; create, update, delete, and regenerate keys for service accounts; transfer workspace ownership and accept or reject transfersManage access to your workspaces: collaborators, service accounts, and ownership transfers (shown with a warning)
task:readGET on ETL tasks, data connections, ETL mappings, monitoring tasks and rules, data product tasks, transformations, rating curves, task runs, and monitoring site task summariesView your data loading, monitoring, and data product tasks, their settings, and run history
task:writePOST, PATCH, and DELETE on the same task resourcesCreate, change, and delete tasks and data connections (shown with a note)
task:runPOST /api/ogc/collections/{collection}/items/{task_id}/trigger, where {collection} is etl-tasks, monitoring-tasks, or data-product-tasksRun your tasks on demand

Scopes don't imply each other. A token with data:write can't read, and a token with task:run can't read the runs it starts, so request each scope your app uses. Scopes only decide which endpoints a token can call. The user's workspace roles still decide which records it can see and change.

Sending the token ​

Send the access token in the Authorization header of each request:

http
GET /api/ogc/collections/workspaces/items
Authorization: Bearer <access token>

In Python, pass the token to hydroserverpy as access_token. To keep long-running code working after the token expires, pass a function that returns a current token instead. It's called before each request. See the Python Client Reference.

python
from hydroserverpy import HydroServer

hs_api = HydroServer(host, access_token=get_access_token)

In TypeScript, pass @hydroserver/client an accessTokenProvider that returns a current token. See Tokens managed by your app.

ts
await createHydroServer({ host, accessTokenProvider: getAccessToken });

iam:write is shown with a warning. A token with this scope can create service accounts and add collaborators, and both keep working after the user revokes your app: a service account's API key doesn't expire with the token that created it. HydroServer allows this so that apps can automate access management, and tells the user before they approve. Workspace users whose role lets them manage service accounts and collaborators can review and delete them from the workspace's access control settings in the Data Management app.

task:write is shown with a note that tasks can write observations to the user's datastreams and send email.

Request these scopes only if your app manages access or tasks.

Missing scopes ​

A request with a valid token that lacks the endpoint's scope gets a 403 response:

json
{ "message": "Access token is missing the required scope: workspace:read" }

This applies even to resources that anonymous users can read, such as public workspaces. A token is never treated as anonymous, so an app that sends a token must hold the scope for every endpoint it calls.

The API's landing page (/api/ogc/), conformance declaration (/api/ogc/conformance), and collection metadata (/api/ogc/collections and /api/ogc/collections/{collection_id}) need no scope. They return the same response to every caller, with or without a token.

Included resources ​

The include query parameter isn't checked against scopes. A request can include related records from another scope's resources, for example include=targetDatastream on ETL mappings with only task:read, or include=owner on workspaces with only workspace:read. Included records are still limited to ones the user can view.