Knogin
[Contrat public curé]

API d'Intégration Externe

Cette page documente uniquement le contrat stable d’intégration externe. Elle se limite volontairement aux endpoints et garanties de transport nécessaires aux intégrateurs approuvés.

Docs lisibles par machineDemander un accès avancé

Périmètre de sécurité

This documentation covers the stable external integration contract only. Platform internals, administrative routes, schema-level discovery, and partner-only capabilities are intentionally withheld from the public surface.

Les noms de routes, exemples de tokens et détails de transport restent en anglais canonique pour correspondre exactement au contrat public.

Vérification JWTOAuth et service tokensWebhooksTransport GraphQL uniquementPas de dump de schémaPas de routes internes

URLs de base

Service d'auth
https://auth.knogin.com
Transport GraphQL
https://api.knogin.com/graphql
Docs lisibles par machine
https://knogin.com/api/docs
Contrat public

Identité et enregistrement d'app

Enregistrez une intégration, consultez les scopes approuvés et gérez la gouvernance d’une app externe.

GET
/v1/platform/scopes

List available scopes

Returns the scope catalog that external apps can request during registration and token issuance.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Use this endpoint to build consent or admin approval workflows around approved scopes.
  • Do not assume unpublished scopes exist or are available to your tenant.
Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/platform/scopes \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "scopes": [
    {
      "name": "webhooks:write",
      "description": "Create and update outbound webhook subscriptions"
    }
  ]
}
GET/POST
/v1/platform/apps

Create and list platform apps

Creates an external integration app record or enumerates the apps already registered for the tenant.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Register a named app before attempting OAuth authorization code or client credentials flows.
  • The response includes client metadata, approved grants, and tenancy context.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Case sync connector",
    "grant_types": ["client_credentials"],
    "redirect_uris": [],
    "requested_scopes": ["webhooks:write"]
  }'

Réponse

{
  "client_id": "app_123",
  "client_secret": "<write-once-secret>",
  "grant_types": ["client_credentials"],
  "requested_scopes": ["webhooks:write"]
}
GET
/v1/platform/apps/{client_id}

Inspect an integration app

Fetches the current metadata and governance state for a registered app by client identifier.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.
Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/platform/apps/app_123 \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "client_id": "app_123",
  "name": "Case sync connector",
  "grant_types": ["client_credentials"],
  "governance": {
    "allow_service_tokens": true
  }
}
PATCH
/v1/platform/apps/{client_id}/governance

Update app governance

Adjusts governance flags for an existing app without exposing tenant-wide administrative controls.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Admins client
Stabilité
Stable
  • Use governance updates to constrain redirects, service token usage, and other tenant-approved behaviors.
  • This surface is scoped to the app identified in the path.
Exemple de requête et de réponse

Requête

curl -X PATCH https://auth.knogin.com/v1/platform/apps/app_123/governance \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_service_tokens": true,
    "enforce_pkce": true
  }'

Réponse

{
  "client_id": "app_123",
  "governance": {
    "allow_service_tokens": true,
    "enforce_pkce": true
  }
}
Contrat public

OAuth et service tokens

Utilisez des flux de tokens approuvés pour des intégrations déléguées par utilisateur ou machine-to-machine.

GET
/v1/oauth/authorize

Start OAuth authorization code flow

Initiates the authorization flow for integrations that act on behalf of a signed-in user.

Host
https://auth.knogin.com
Auth
OAuth authorization code
Audience
Intégrateurs externes
Stabilité
Stable
  • Authorization requests should use the redirect URIs and scopes already approved on the platform app.
  • PKCE should be used whenever a confidential client secret is not available.
Exemple de requête et de réponse

Requête

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

Réponse

302 redirect to the registered redirect URI with either ?code=<authorization-code> or an OAuth error.
POST
/v1/oauth/token

Exchange or mint access tokens

Issues access tokens via authorization code or client credentials without documenting internal password or session flows.

Host
https://auth.knogin.com
Auth
OAuth auth code or client credentials
Audience
Intégrateurs externes
Stabilité
Stable
  • Use authorization code for user-delegated access and client credentials for headless service integrations.
  • Only request scopes that were approved during app registration.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=app_123&client_secret=<client-secret>&scope=webhooks:write"

Réponse

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "webhooks:write"
}
POST
/v1/platform/apps/{client_id}/service-token

Mint a service token

Issues a service token for automation that should not depend on an end-user session.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Admins client
Stabilité
Stable
  • Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.
  • Keep service-token issuance behind tenant admin approval.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/service-token \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["webhooks:write"]
  }'

Réponse

{
  "token": "<service-token>",
  "expires_at": "2026-03-24T10:00:00Z"
}
POST
/v1/platform/apps/{client_id}/rotate-secret

Rotate an app secret

Rotates a confidential client secret so an external integration can recover or rotate credentials safely.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Admins client
Stabilité
Stable
  • Treat the rotated secret as write-once material and replace it in your secret store immediately.
  • Rotate secrets before revoking old credentials from automation.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/rotate-secret \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "client_id": "app_123",
  "client_secret": "<new-write-once-secret>"
}
Contrat public

JWKS et vérification de token

Vérifiez les JWT émis par Knogin avec les clés publiques.

GET
/.well-known/jwks.json

OpenID-compatible JWKS discovery

Publishes public signing keys at the well-known JWKS path for standards-based token validation.

Host
https://auth.knogin.com
Auth
Public
Audience
Intégrateurs externes
Stabilité
Stable
  • Use the key identifier in the JWT header to select the correct public key.
  • Cache JWKS responses according to your verifier policy and refresh on unknown key IDs.
Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/.well-known/jwks.json

Réponse

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}
GET
/v1/auth/jwks.json

Versioned JWKS endpoint

Provides the same public signing material under the auth-service versioned API namespace.

Host
https://auth.knogin.com
Auth
Public
Audience
Intégrateurs externes
Stabilité
Stable
  • Use this variant when your API client standardizes on versioned endpoints.
Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/auth/jwks.json

Réponse

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}
Contrat public

Diffusion d’événements et webhooks

Créez, testez et observez les livraisons webhook sortantes pour des intégrations approuvées.

GET/POST
/v1/webhooks

Create and list webhooks

Manages outbound webhook subscriptions used to deliver approved event notifications to an external system.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Create subscriptions only for events your integration has been approved to receive.
  • Outbound webhook secrets should be stored and rotated like any other integration credential.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/webhooks \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://integrator.example/webhooks/argus",
    "events": ["incident.updated"],
    "secret": "<signing-secret>"
  }'

Réponse

{
  "id": "wh_123",
  "url": "https://integrator.example/webhooks/argus",
  "events": ["incident.updated"]
}
GET/PUT/DELETE
/v1/webhooks/{webhook_id}

Inspect, update, or delete a webhook

Manages an individual webhook subscription by identifier.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Use update operations to rotate secrets or adjust event selections without recreating the subscription.
Exemple de requête et de réponse

Requête

curl -X PUT https://auth.knogin.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["incident.updated", "incident.closed"]
  }'

Réponse

{
  "id": "wh_123",
  "events": ["incident.updated", "incident.closed"]
}
GET
/v1/webhooks/{webhook_id}/deliveries

Review delivery attempts

Returns historical delivery attempts for a webhook so integrators can debug retries and downstream failures.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Use delivery history instead of internal logs to diagnose receiver behavior.
  • Delivery metadata is limited to the webhook in scope.
Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/webhooks/wh_123/deliveries \
  -H "Authorization: Bearer <access-token>"

Réponse

{
  "deliveries": [
    {
      "id": "dlv_123",
      "status": "succeeded",
      "attempted_at": "2026-03-23T12:00:00Z"
    }
  ]
}
POST
/v1/webhooks/{webhook_id}/test

Send a test webhook

Triggers a synthetic delivery to validate receiver configuration before enabling production traffic.

Host
https://auth.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Use test deliveries when rotating secrets or validating a new endpoint.
Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/webhooks/wh_123/test \
  -H "Authorization: Bearer <access-token>"

Réponse

{
  "delivery_id": "dlv_test_123",
  "status": "queued"
}
Contrat public

Contrat de transport GraphQL

Connectez-vous au transport GraphQL partagé sans publier le schéma ni l’inventaire des opérations.

POST
/graphql

Use the shared GraphQL transport

Connect to the GraphQL endpoint with bearer tokens and tenant scoping, while operation bundles remain curated and access-controlled.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Intégrateurs externes
Stabilité
Stable
  • Public documentation covers transport, headers, tenancy, and error handling only.
  • Schema dumps, playground access, introspection guidance, and unpublished operations are excluded from the public contract.
  • Approved partners receive curated operation bundles tied to explicit integration workflows.
Exemple de requête et de réponse

Requête

curl -X POST https://api.knogin.com/graphql \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: <tenant-id>" \
  -d '{
    "query": "<approved GraphQL document>",
    "variables": {}
  }'

Réponse

{
  "data": {
    "result": "Returned for your approved operation bundle"
  }
}
Disponible sur demande

Capacités avancées disponibles sur demande

Les APIs élargies, bundles GraphQL curés et la fédération d’entreprise restent derrière un accès revu.

/api/v1/platform/*

Platform control-plane APIs

Expanded control-plane workflows under /api/v1/platform are available only through approved partner or customer programs.

Host
https://api.knogin.com
Auth
Request access
Audience
Partenaires stratégiques
Stabilité
Approuvé sur demande
  • Public docs intentionally stop at a high-level capability description.
  • Examples include deployment packages, automations, agents, marketplace flows, and release operations.
La documentation détaillée de cette capacité n'est disponible que via le processus d'intégration avec revue.
Demander un accès
Curated GraphQL operations by approved workflow

Curated GraphQL operation bundles

Approved integrations can receive a narrow set of GraphQL operations derived from vetted FE2 workflows instead of full schema discovery.

Host
https://api.knogin.com
Auth
Request access
Audience
Partenaires stratégiques
Stabilité
Approuvé sur demande
  • Examples include incident webhook configuration flows and other explicitly approved bundles.
  • This is the mechanism for exposing integrations without publishing the full GraphQL schema.
La documentation détaillée de cette capacité n'est disponible que via le processus d'intégration avec revue.
Demander un accès
/v1/saml/*

Enterprise federation and SAML

Federation setup and SAML onboarding are handled through guided implementation rather than a self-serve public blueprint.

Host
https://auth.knogin.com
Auth
Request access
Audience
Admins client
Stabilité
Approuvé sur demande
  • Enterprise identity integrations require tenant-specific coordination and are not documented as an open public API.
La documentation détaillée de cette capacité n'est disponible que via le processus d'intégration avec revue.
Demander un accès

Besoin d’accéder à des intégrations avancées ?

Utilisez la demande d’intégration pour des bundles GraphQL curés, des APIs avancées de plateforme, la fédération d’entreprise ou un sandbox.