Authentication

Protected PIE V2 endpoints require a Cognito-issued JWT in the Authorization header.

Authorization: Bearer <access_token>

The API does not issue tokens. Your application obtains a token from AWS Cognito using the flow configured for your integration.

Token sources

Machine clients

Server-to-server integrations normally use the Cognito client credentials grant. The token includes a space-separated scope claim. Each streamline/... scope maps to one or more PIE operation permissions.

curl -s -X POST "https://<your-cognito-domain>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<app-client-id>" \
  -d "client_secret=<app-client-secret>" \
  -d "scope=streamline/read_models streamline/run_inference"

Each machine client is configured with a tenant access class by the platform team. Platform clients act on every tenant and can use the global model routes. Tenant clients are limited to a fixed set of tenants: they can call tenant-scoped routes (/v2/clients/{client_id}/...) only for tenants in that set, cannot use the global model registry routes, and can read a job only when it belongs to one of their tenants. For machine clients, streamline/admin grants full operation access but does not expand tenant reach beyond the configured access class.

Human users

Human users authenticate with their Cognito username and password using the user-pool app client. PIE does not receive the password; it only receives the access token returned by Cognito.

Human access tokens include cognito:groups. The admin group grants full operation access and access to all registry clients.

Non-admin users must belong to a tenant group named client:{registry_client_id} to call routes under /v2/clients/{registry_client_id}/....

Two authorization checks

Every protected request is checked on two axes:

1. Operation permission: Whether the token may perform the action, such as reading models, managing domains, initializing services, or running inference.
2. Registry client access: Whether the token may use the client_id in the path for tenant-scoped routes, and whether it may access a given tenant-owned job.

Missing or invalid tokens return 401. Valid tokens without the required permission or tenant access return 403.

Common scopes

Request the smallest scope set your integration needs.

Scope	Typical use
streamline/read_models	Read model definitions, versions, and jobs.
streamline/write_models	Create or update models and versions.
streamline/train_model	Start model training jobs.
streamline/run_inference	Start inference through direct model routes or assignments.
streamline/client_read	Read tenant, domain, and service state.
streamline/service_init	Initialize services.
streamline/manage_services	Update services and bind service-scoped assignments.
streamline/manage_domains	Create domains, features, and the domain default assignment. Includes manage_services.
streamline/complete_job	Report handler job completion.
streamline/admin	Full operation access.

Public routes

GET /v2/health is public. All other useful API routes should be treated as protected.