User authorization

User authorization lets a user specify the business resources an Application may operate on and how long access remains valid. This guide covers querying options, creating grants, checking access, and revoking grants.

API permissions, user consent, and resource access are checked separately. Creating a grant does not purchase a product or increase allowance.

Prerequisites

Before creating, renewing or checking a grant, configure the application's user identity and required API Scopes as described in Entry points and permissions, then sign in with authorization code + PKCE. Listing and revocation require only a valid person session and current organization membership; they remain available when business Scopes are withdrawn or the application is unavailable. Send the user Bearer and X-GV-Organization-ID on every request. The user must belong to the selected customer Organization. Do not use a service Token or supply a different user or Organization in the body.

Endpoint list

Endpoint	Description
GET /open-platform/v1/delegated-grant-options	Read available options for the current application's user OAuth Client
GET /open-platform/v1/delegated-grants	Read your grants; optionally filter by status=active|revoked|expired
POST /open-platform/v1/delegated-grants	Create or update your grant by version
POST /open-platform/v1/delegated-grants/{id}:revoke	Revoke your grant using its current version
POST /open-platform/v1/delegated-grants:authorize	Check whether the current request is within an effective grant

These shared endpoints do not require a separate API product. When creating or checking a grant, the Token, application user identity and API permission must all include the requested business Scopes.

Query options and create a grant

curl --request GET \
  --url "${GOODVISION_API_BASE}/open-platform/v1/delegated-grant-options?application_id=${GOODVISION_APPLICATION_ID}" \
  --header "Authorization: Bearer ${GOODVISION_USER_ACCESS_TOKEN}" \
  --header "X-GV-Organization-ID: ${GOODVISION_CUSTOMER_ORGANIZATION_ID}"

Response items contains available application_id, application_name, environment, environment_binding_id, api_product_id, scopes and product_codes. Options reflect effective permissions for the current application, environment and API product. product_codes proposes resources only when actual commercial bindings exist. An empty array does not establish consent; use exact resources confirmed by their business Owner when creating a grant.

The platform derives the Client and environment binding from the current source. Creation and check requests select the application, environment and API product; they do not accept an OAuth Profile, subscription or environment binding ID. For other products, use the resource type and scope in their guide.

Show the purpose, Scopes, resources and expiry to the user. After confirmation, call the creation endpoint with a stable Idempotency-Key. This Token product example requires replacing every placeholder:

{
  "application_id": "<application_id>",
  "environment": "sandbox",
  "api_product_id": "<api_product_id>",
  "scopes": ["inference.models.read", "inference.invoke"],
  "resource_scope": {"resource_type": "token_product", "resource_ids": ["<product_code>"]},
  "expires_at": "<future RFC3339 timestamp>",
  "version": 0
}

Creation returns 201; an update returns 200. Retain the returned id, application_id, environment, environment_binding_id, api_product_id, version, status, expires_at and actual scope. Updates use the positive version read from the existing grant. Independent order payment uses order_payment_product as documented in its guide, rather than the Token resource type.

Query, check, and revoke a grant

The list returns {"items": [...]} containing only the current user's grants in the selected Organization. An active status does not replace authorization on each request.

The check accepts grant_id, application_id, environment, api_product_id, scopes and resource_scope. Use the effective grant from the previous step. Requested resources and scopes must fall within its authorized range.

200 with authorized=true confirms this request's grant scope check. The target API still checks current resource access. This operation is read-only and requires no idempotency key.

To revoke, call the original grant ID's :revoke endpoint with a fixed Idempotency-Key and {"version": <current_version>, "reason": "User no longer uses this application"}. Reasons must be 3–500 characters. Retry with the same key and body.

Stop using the grant after status=revoked. Renewed consent creates a new record. Expired grants also cause later calls to be rejected.

Errors and recovery

Status or condition	Action
401/403	Check sign-in, customer organization, user Client and business scopes
409	Read the current version and status, then ask the user to confirm; do not expand scope to force a retry
400/422	Correct fields, version and future expiry
503 or a write timeout	Keep the original body and Idempotency-Key; query state and follow Idempotency and retries

Keep the result pending until confirmed.

Next: Token API · Independent order payment

User correlation and consent

Users and customer spaces returns aliases and current membership, without replacing consent, API scopes or resource privileges. Two Applications may correlate one person while retaining independent grants and revocation.