{"id":"oauth-service-tokens","title":"OAuth and service tokens","description":"Use OAuth 2.0 authorization code or client credentials flows, then rotate credentials without exposing internal auth flows.","lastUpdated":"2026-03-23","sections":[{"id":"oauth-authorize","title":"GET /v1/oauth/authorize · Start OAuth authorization code flow","content":"Route: GET /v1/oauth/authorize\nHost: https://auth.knogin.com\nAuth: OAuth 2.0 authorization code\nAudience: External integrators\nStability: Stable\n\nInitiates the authorization flow for integrations that act on behalf of a signed-in user.\n\nIntegration notes:\n- Authorization requests should use the redirect URIs and scopes already approved on the platform app.\n- PKCE should be used whenever a confidential client secret is not available.","codeExamples":[{"language":"bash","code":"https://auth.knogin.com/v1/oauth/authorize?response_type=code&client_id=app_123&redirect_uri=https%3A%2F%2Fintegrator.example%2Fcallback&scope=webhooks%3Awrite&state=<opaque-state>&code_challenge=<pkce-challenge>&code_challenge_method=S256","description":"Request example"},{"language":"text","code":"302 redirect to the registered redirect URI with either ?code=<authorization-code> or an OAuth error.","description":"Response example"}]},{"id":"oauth-token","title":"POST /v1/oauth/token · Exchange or mint access tokens","content":"Route: POST /v1/oauth/token\nHost: https://auth.knogin.com\nAuth: OAuth 2.0 authorization code or client credentials\nAudience: External integrators\nStability: Stable\n\nIssues access tokens via authorization code or client credentials without documenting internal password or session flows.\n\nIntegration notes:\n- Use authorization code for user-delegated access and client credentials for headless service integrations.\n- Only request scopes that were approved during app registration.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/oauth/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials&client_id=app_123&client_secret=<client-secret>&scope=webhooks:write\"","description":"Request example"},{"language":"json","code":"{\n  \"access_token\": \"<jwt>\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"scope\": \"webhooks:write\"\n}","description":"Response example"}]},{"id":"platform-service-token","title":"POST /v1/platform/apps/{client_id}/service-token · Mint a service token","content":"Route: POST /v1/platform/apps/{client_id}/service-token\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nIssues a service token for automation that should not depend on an end-user session.\n\nIntegration notes:\n- Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.\n- Keep service-token issuance behind tenant admin approval.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/service-token \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"scopes\": [\"webhooks:write\"]\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"token\": \"<service-token>\",\n  \"expires_at\": \"2026-03-24T10:00:00Z\"\n}","description":"Response example"}]},{"id":"platform-rotate-secret","title":"POST /v1/platform/apps/{client_id}/rotate-secret · Rotate an app secret","content":"Route: POST /v1/platform/apps/{client_id}/rotate-secret\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nRotates a confidential client secret so an external integration can recover or rotate credentials safely.\n\nIntegration notes:\n- Treat the rotated secret as write-once material and replace it in your secret store immediately.\n- Rotate secrets before revoking old credentials from automation.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/rotate-secret \\\n  -H \"Authorization: Bearer <admin-access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"client_id\": \"app_123\",\n  \"client_secret\": \"<new-write-once-secret>\"\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","jwks-token-verification","event-delivery-webhooks","graphql-transport-contract"],"markdown":"# OAuth and service tokens\n\nUse OAuth 2.0 authorization code or client credentials flows, then rotate credentials without exposing internal auth flows.\n\n## GET /v1/oauth/authorize · Start OAuth authorization code flow\n\nRoute: GET /v1/oauth/authorize\nHost: https://auth.knogin.com\nAuth: OAuth 2.0 authorization code\nAudience: External integrators\nStability: Stable\n\nInitiates the authorization flow for integrations that act on behalf of a signed-in user.\n\nIntegration notes:\n- Authorization requests should use the redirect URIs and scopes already approved on the platform app.\n- PKCE should be used whenever a confidential client secret is not available.\n\nRequest example\n\n```bash\nhttps://auth.knogin.com/v1/oauth/authorize?response_type=code&client_id=app_123&redirect_uri=https%3A%2F%2Fintegrator.example%2Fcallback&scope=webhooks%3Awrite&state=<opaque-state>&code_challenge=<pkce-challenge>&code_challenge_method=S256\n```\n\nResponse example\n\n```text\n302 redirect to the registered redirect URI with either ?code=<authorization-code> or an OAuth error.\n```\n\n## POST /v1/oauth/token · Exchange or mint access tokens\n\nRoute: POST /v1/oauth/token\nHost: https://auth.knogin.com\nAuth: OAuth 2.0 authorization code or client credentials\nAudience: External integrators\nStability: Stable\n\nIssues access tokens via authorization code or client credentials without documenting internal password or session flows.\n\nIntegration notes:\n- Use authorization code for user-delegated access and client credentials for headless service integrations.\n- Only request scopes that were approved during app registration.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/oauth/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials&client_id=app_123&client_secret=<client-secret>&scope=webhooks:write\"\n```\n\nResponse example\n\n```json\n{\n  \"access_token\": \"<jwt>\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"scope\": \"webhooks:write\"\n}\n```\n\n## POST /v1/platform/apps/{client_id}/service-token · Mint a service token\n\nRoute: POST /v1/platform/apps/{client_id}/service-token\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nIssues a service token for automation that should not depend on an end-user session.\n\nIntegration notes:\n- Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.\n- Keep service-token issuance behind tenant admin approval.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/platform/apps/app_123/service-token \\\n  -H \"Authorization: Bearer <admin-access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"scopes\": [\"webhooks:write\"]\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"token\": \"<service-token>\",\n  \"expires_at\": \"2026-03-24T10:00:00Z\"\n}\n```\n\n## POST /v1/platform/apps/{client_id}/rotate-secret · Rotate an app secret\n\nRoute: POST /v1/platform/apps/{client_id}/rotate-secret\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: Customer administrators\nStability: Stable\n\nRotates a confidential client secret so an external integration can recover or rotate credentials safely.\n\nIntegration notes:\n- Treat the rotated secret as write-once material and replace it in your secret store immediately.\n- Rotate secrets before revoking old credentials from automation.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/platform/apps/app_123/rotate-secret \\\n  -H \"Authorization: Bearer <admin-access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"client_id\": \"app_123\",\n  \"client_secret\": \"<new-write-once-secret>\"\n}\n```\n\n## Related Topics\n\n- [Identity and app registration](https://knogin.com/api/docs/identity-app-registration)\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"]}}