{"id":"identity-app-registration","title":"Identity and app registration","description":"Register an integration, inspect allowed scopes, and manage governance settings for an external app.","lastUpdated":"2026-03-23","sections":[{"id":"platform-scopes","title":"GET /v1/platform/scopes · List available scopes","content":"Route: GET /v1/platform/scopes\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the scope catalog that external apps can request during registration and token issuance.\n\nIntegration notes:\n- Use this endpoint to build consent or admin approval workflows around approved scopes.\n- Do not assume unpublished scopes exist or are available to your tenant.","codeExamples":[{"language":"bash","code":"curl https://auth.knogin.com/v1/platform/scopes \\\n  -H \"Authorization: Bearer <admin-access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"scopes\": [\n    {\n      \"name\": \"webhooks:write\",\n      \"description\": \"Create and update outbound webhook subscriptions\"\n    }\n  ]\n}","description":"Response example"}]},{"id":"platform-apps-collection","title":"GET/POST /v1/platform/apps · Create and list platform apps","content":"Route: GET/POST /v1/platform/apps\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreates an external integration app record or enumerates the apps already registered for the tenant.\n\nIntegration notes:\n- Register a named app before attempting OAuth authorization code or client credentials flows.\n- The response includes client metadata, approved grants, and tenancy context.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/platform/apps \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Case sync connector\",\n    \"grant_types\": [\"client_credentials\"],\n    \"redirect_uris\": [],\n    \"requested_scopes\": [\"webhooks:write\"]\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"client_id\": \"app_123\",\n  \"client_secret\": \"<write-once-secret>\",\n  \"grant_types\": [\"client_credentials\"],\n  \"requested_scopes\": [\"webhooks:write\"]\n}","description":"Response example"}]},{"id":"platform-app-detail","title":"GET /v1/platform/apps/{client_id} · Inspect an integration app","content":"Route: GET /v1/platform/apps/{client_id}\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nFetches the current metadata and governance state for a registered app by client identifier.\n\nIntegration notes:\n- Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.","codeExamples":[{"language":"bash","code":"curl https://auth.knogin.com/v1/platform/apps/app_123 \\\n  -H \"Authorization: Bearer <admin-access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"client_id\": \"app_123\",\n  \"name\": \"Case sync connector\",\n  \"grant_types\": [\"client_credentials\"],\n  \"governance\": {\n    \"allow_service_tokens\": true\n  }\n}","description":"Response example"}]},{"id":"platform-governance","title":"PATCH /v1/platform/apps/{client_id}/governance · Update app governance","content":"Route: PATCH /v1/platform/apps/{client_id}/governance\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nAdjusts governance flags for an existing app without exposing tenant-wide administrative controls.\n\nIntegration notes:\n- Use governance updates to constrain redirects, service token usage, and other tenant-approved behaviors.\n- This surface is scoped to the app identified in the path.","codeExamples":[{"language":"bash","code":"curl -X PATCH https://auth.knogin.com/v1/platform/apps/app_123/governance \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"allow_service_tokens\": true,\n    \"enforce_pkce\": true\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"client_id\": \"app_123\",\n  \"governance\": {\n    \"allow_service_tokens\": true,\n    \"enforce_pkce\": true\n  }\n}","description":"Response example"}]}],"relatedTopics":["oauth-service-tokens","jwks-token-verification","event-delivery-webhooks","graphql-transport-contract"],"markdown":"# Identity and app registration\n\nRegister an integration, inspect allowed scopes, and manage governance settings for an external app.\n\n## GET /v1/platform/scopes · List available scopes\n\nRoute: GET /v1/platform/scopes\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the scope catalog that external apps can request during registration and token issuance.\n\nIntegration notes:\n- Use this endpoint to build consent or admin approval workflows around approved scopes.\n- Do not assume unpublished scopes exist or are available to your tenant.\n\nRequest example\n\n```bash\ncurl https://auth.knogin.com/v1/platform/scopes \\\n  -H \"Authorization: Bearer <admin-access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"scopes\": [\n    {\n      \"name\": \"webhooks:write\",\n      \"description\": \"Create and update outbound webhook subscriptions\"\n    }\n  ]\n}\n```\n\n## GET/POST /v1/platform/apps · Create and list platform apps\n\nRoute: GET/POST /v1/platform/apps\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreates an external integration app record or enumerates the apps already registered for the tenant.\n\nIntegration notes:\n- Register a named app before attempting OAuth authorization code or client credentials flows.\n- The response includes client metadata, approved grants, and tenancy context.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/platform/apps \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Case sync connector\",\n    \"grant_types\": [\"client_credentials\"],\n    \"redirect_uris\": [],\n    \"requested_scopes\": [\"webhooks:write\"]\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"client_id\": \"app_123\",\n  \"client_secret\": \"<write-once-secret>\",\n  \"grant_types\": [\"client_credentials\"],\n  \"requested_scopes\": [\"webhooks:write\"]\n}\n```\n\n## GET /v1/platform/apps/{client_id} · Inspect an integration app\n\nRoute: GET /v1/platform/apps/{client_id}\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nFetches the current metadata and governance state for a registered app by client identifier.\n\nIntegration notes:\n- Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.\n\nRequest example\n\n```bash\ncurl https://auth.knogin.com/v1/platform/apps/app_123 \\\n  -H \"Authorization: Bearer <admin-access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"client_id\": \"app_123\",\n  \"name\": \"Case sync connector\",\n  \"grant_types\": [\"client_credentials\"],\n  \"governance\": {\n    \"allow_service_tokens\": true\n  }\n}\n```\n\n## PATCH /v1/platform/apps/{client_id}/governance · Update app governance\n\nRoute: PATCH /v1/platform/apps/{client_id}/governance\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nAdjusts governance flags for an existing app without exposing tenant-wide administrative controls.\n\nIntegration notes:\n- Use governance updates to constrain redirects, service token usage, and other tenant-approved behaviors.\n- This surface is scoped to the app identified in the path.\n\nRequest example\n\n```bash\ncurl -X PATCH https://auth.knogin.com/v1/platform/apps/app_123/governance \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"allow_service_tokens\": true,\n    \"enforce_pkce\": true\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"client_id\": \"app_123\",\n  \"governance\": {\n    \"allow_service_tokens\": true,\n    \"enforce_pkce\": true\n  }\n}\n```\n\n## Related Topics\n\n- [OAuth and service tokens](https://knogin.com/api/docs/oauth-service-tokens)\n- [JWKS and token verification](https://knogin.com/api/docs/jwks-token-verification)\n- [Event delivery and webhooks](https://knogin.com/api/docs/event-delivery-webhooks)\n- [GraphQL transport contract](https://knogin.com/api/docs/graphql-transport-contract)","metadata":{"readingTime":"8 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}