[Contrato público curado]

API de Integración Externa

Esta página documenta solo el contrato estable de integración externa. Está limitada deliberadamente a los endpoints y garantías de transporte que necesitan los integradores aprobados.

Docs legibles por máquina Solicitar acceso avanzado

Límite de seguridad

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.

Los nombres de rutas, ejemplos de tokens y detalles de transporte permanecen en inglés canónico para alinearse exactamente con el contrato público.

Validación JWTOAuth y service tokensWebhooksSolo transporte GraphQLSin volcado de esquemaSin rutas internas

URLs base

Servicio de auth: https://auth.knogin.com
Transporte GraphQL: https://api.knogin.com/graphql
Docs legibles por máquina: https://knogin.com/api/docs

Contrato público

Identidad y registro de apps

Registra una integración, consulta scopes aprobados y gestiona gobernanza para una app externa.

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
Audiencia: Integradores externos
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Register a named app before attempting OAuth authorization code or client credentials flows.
The response includes client metadata, approved grants, and tenancy context.

Ejemplo de solicitud y respuesta

Solicitud

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"]
  }'

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

{
  "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
Audiencia: Admins del cliente
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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
  }'

Respuesta

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

Contrato público

OAuth y service tokens

Usa flujos de token aprobados para integraciones delegadas por usuario o 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
Audiencia: Integradores externos
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

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
Audiencia: Integradores externos
Estabilidad: Estable

Use authorization code for user-delegated access and client credentials for headless service integrations.
Only request scopes that were approved during app registration.

Ejemplo de solicitud y respuesta

Solicitud

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"

Respuesta

{
  "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
Audiencia: Admins del cliente
Estabilidad: Estable

Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.
Keep service-token issuance behind tenant admin approval.

Ejemplo de solicitud y respuesta

Solicitud

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"]
  }'

Respuesta

{
  "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
Audiencia: Admins del cliente
Estabilidad: Estable

Treat the rotated secret as write-once material and replace it in your secret store immediately.
Rotate secrets before revoking old credentials from automation.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

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

Contrato público

JWKS y verificación de tokens

Verifica JWT emitidos por Knogin contra claves públicas.

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
Audiencia: Integradores externos
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Use this variant when your API client standardizes on versioned endpoints.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

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

Contrato público

Entrega de eventos y webhooks

Crea, prueba y observa entregas salientes de webhook para integraciones aprobadas.

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
Audiencia: Integradores externos
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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>"
  }'

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Use update operations to rotate secrets or adjust event selections without recreating the subscription.

Ejemplo de solicitud y respuesta

Solicitud

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"]
  }'

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Use delivery history instead of internal logs to diagnose receiver behavior.
Delivery metadata is limited to the webhook in scope.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

{
  "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
Audiencia: Integradores externos
Estabilidad: Estable

Use test deliveries when rotating secrets or validating a new endpoint.

Ejemplo de solicitud y respuesta

Solicitud

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

Respuesta

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

Contrato público

Contrato de transporte GraphQL

Conéctate al transporte GraphQL compartido sin publicar esquema ni inventario de operaciones.

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
Audiencia: Integradores externos
Estabilidad: Estable

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.

Ejemplo de solicitud y respuesta

Solicitud

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": {}
  }'

Respuesta

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

Disponible bajo solicitud

Capacidades avanzadas disponibles bajo solicitud

APIs ampliadas, bundles GraphQL curados y federación empresarial quedan detrás del acceso revisado.

/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
Audiencia: Partners estratégicos
Estabilidad: Aprobado bajo solicitud

Public docs intentionally stop at a high-level capability description.
Examples include deployment packages, automations, agents, marketplace flows, and release operations.

La documentación detallada de esta capacidad solo está disponible mediante el proceso de integración con revisión.

Solicitar acceso

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
Audiencia: Partners estratégicos
Estabilidad: Aprobado bajo solicitud

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 documentación detallada de esta capacidad solo está disponible mediante el proceso de integración con revisión.

Solicitar acceso

/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
Audiencia: Admins del cliente
Estabilidad: Aprobado bajo solicitud

Enterprise identity integrations require tenant-specific coordination and are not documented as an open public API.

La documentación detallada de esta capacidad solo está disponible mediante el proceso de integración con revisión.

Solicitar acceso

¿Necesitas acceso a integraciones avanzadas?

Usa el flujo de solicitud de integración para bundles GraphQL curados, APIs avanzadas de plataforma, federación empresarial o sandbox.