QUERY https://dev.api.kydhub.com/api/v1/persons/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "fields": ["name", "addresses.shipping", "profile.occupation", "created_at"],
  "response_profile": "standard",
  "format": {
    "names": "surname_first_comma",
    "addresses": "multiline",
    "text": "locale_title_case",
    "dates": "localized_datetime",
    "locale": "es-US",
    "include_raw": true
  }
}

{
  "status": "error",
  "error": {
    "code": "data_grant_required",
    "person_kyd": "BOB.CARTER",
    "service_name": "acme-checkout",
    "requested_fields": ["name"],
    "required_permissions": [
      {"permission": "person.identity:read", "reason": "Required to identify the requested person in the Data API flow."},
      {"permission": "person.name:read", "reason": "Required to read the requested field: name."}
    ],
    "resolution": {
      "action": "request_data_grant",
      "endpoint": "POST /api/v1/data-grants/requests",
      "request_body": {
        "subject_type": "person",
        "subject_kyd": "BOB.CARTER",
        "requested_scopes": ["person.identity:read", "person.name:read"],
        "purpose": "Allow acme-checkout to read the person's name.",
        "external_reference": "acme-checkout"
      }
    }
  }
}

{
  "person_id": "per_7Q9M2K4R",
  "person_kyd": "BOB.CARTER",
  "response_profile_used": "standard",
  "format_used": {
    "names": "surname_first_comma",
    "addresses": "multiline",
    "text": "locale_title_case",
    "dates": "localized_datetime",
    "locale": "es-US",
    "include_raw": true
  },
  "fields": {
    "name": {
      "raw": "Bob José de la Cruz O'Neill García",
      "formatted": "O'Neill García, Bob José de la Cruz"
    },
    "addresses": {
      "shipping": {
        "raw": {
          "line1": "1200 Brickell Ave",
          "line2": "Suite 800",
          "city": "Miami",
          "region": "FL",
          "postal_code": "33131",
          "country": "US"
        },
        "formatted": "1200 Brickell Ave\nSuite 800\nMiami, FL 33131\nUS"
      }
    },
    "profile": {
      "occupation": {
        "raw": "software engineer",
        "formatted": "Software engineer"
      }
    },
    "created_at": {
      "raw": "2026-06-30T18:40:00Z",
      "formatted": "30/06/2026 18:40 UTC"
    }
  }
}

{
  "given_names": ["Bob", "José"],
  "middle_names": ["de la Cruz"],
  "family_names": ["O'Neill", "García"],
  "full_name": "Bob José de la Cruz O'Neill García"
}

{
  "fields": ["name"],
  "format": {
    "names": "ascii_upper",
    "include_raw": true
  }
}

{
  "name": {
    "raw": "Bob José de la Cruz O'Neill García",
    "formatted": "BOB JOSE DE LA CRUZ ONEILL GARCIA",
    "format_used": "ascii_upper"
  }
}

{
  "line1": "1200 Brickell Ave",
  "line2": "Suite 800",
  "city": "Miami",
  "region": "FL",
  "postal_code": "33131",
  "country": "US"
}

{
  "address": {
    "formatted": "1200 Brickell Ave\nSuite 800\nMiami FL 33131\nUNITED STATES",
    "format_used": "postal",
    "country_format_used": "US"
  }
}

Inteligencia Artificial & Automatización

2026-06-30T18:40:00Z

{
  "error": "invalid_format",
  "message": "Unsupported presentation format.",
  "field": "format.names",
  "allowed_formats": [
    "as_recorded",
    "given_first",
    "surname_first_comma",
    "surname_first_space",
    "locale_title_case",
    "upper",
    "lower",
    "ascii",
    "ascii_upper",
    "initials",
    "initials_dotted"
  ]
}

curl -X QUERY https://dev.api.kydhub.com/api/v1/persons/query \
  -H "X-API-KEY: $KYDHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_kyd":"BOB.CARTER","fields":["full_name"]}'

import os
import httpx
from fastapi import FastAPI, HTTPException

app = FastAPI()
KYDHUB_BASE_URL = os.getenv("KYDHUB_BASE_URL", "https://dev.api.kydhub.com/api/v1")
api_key = os.getenv("KYDHUB_API_KEY", "set-in-secret-manager")

@app.get("/internal/kydhub/person/{person_kyd}")
async def get_person(person_kyd: str):
    payload = {
        "person_kyd": person_kyd,
        "service_name": "acme-checkout",
        "fields": ["full_name", "profile.display_name"],
    }
    headers = {
        "X-API-KEY": api_key,
        "Content-Type": "application/json",
    }
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.request("QUERY", f"{KYDHUB_BASE_URL}/api/v1/persons/query", json=payload, headers=headers)
    if response.status_code >= 400:
        raise HTTPException(status_code=response.status_code, detail=response.json())
    return response.json()

import express from "express";

const app = express();
app.use(express.json());

const KYDHUB_BASE_URL = process.env.KYDHUB_BASE_URL ?? "https://dev.api.kydhub.com/api/v1";
const apiKey = process.env.KYDHUB_API_KEY ?? "set-in-secret-manager";

app.post("/internal/kydhub/company", async (req, res) => {
  const response = await fetch(${KYDHUB_BASE_URL}/api/v1/companies/query, {
    method: "QUERY",
    headers: {
      "X-API-KEY": apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      company_kyd: req.body.company_kyd,
      service_name: "acme-supplier-review",
      fields: ["legal_name", "status", "profile.industry"]
    })
  });

  const body = await response.json();
  res.status(response.status).json(body);
});

package main

import (
  "bytes"
  "encoding/json"
  "net/http"
  "os"
  "time"
)

func queryCompanyLocations(companyKYD string) (*http.Response, error) {
  baseURL := os.Getenv("KYDHUB_BASE_URL")
  if baseURL == "" { baseURL = "https://dev.api.kydhub.com/api/v1" }

  payload := map[string]any{
    "company_kyd": companyKYD,
    "service_name": "acme-supplier-review",
    "fields": []string{"locations.city", "locations.country"},
  }
  body, err := json.Marshal(payload)
  if err != nil { return nil, err }

  req, err := http.NewRequest("QUERY", baseURL+"/api/v1/companies/query", bytes.NewReader(body))
  if err != nil { return nil, err }
  req.Header.Set("X-API-KEY", os.Getenv("KYDHUB_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{Timeout: 10 * time.Second}
  return client.Do(req)
}

import { shell } from "electron";
import crypto from "node:crypto";

const state = crypto.randomUUID();
const nonce = crypto.randomUUID();
const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");

const url = new URL("https://dev.auth.kydhub.com/oauth/authorize");
url.searchParams.set("client_id", "acme_desktop_client");
url.searchParams.set("redirect_uri", "acme://oauth/callback");
url.searchParams.set("response_type", "code");
url.searchParams.set("scope", "openid kwid profile");
url.searchParams.set("state", state);
url.searchParams.set("nonce", nonce);
url.searchParams.set("code_challenge", codeChallenge);
url.searchParams.set("code_challenge_method", "S256");

shell.openExternal(url.toString());

use open;
use url::Url;

fn start_kydhub_login(code_challenge: &str, state: &str, nonce: &str) -> anyhow::Result<()> {
    let mut url = Url::parse("https://dev.auth.kydhub.com/oauth/authorize")?;
    url.query_pairs_mut()
        .append_pair("client_id", "acme_desktop_client")
        .append_pair("redirect_uri", "acme://oauth/callback")
        .append_pair("response_type", "code")
        .append_pair("scope", "openid kwid profile")
        .append_pair("state", state)
        .append_pair("nonce", nonce)
        .append_pair("code_challenge", code_challenge)
        .append_pair("code_challenge_method", "S256");

    open::that(url.as_str())?;
    Ok(())
}

QUERY https://dev.api.kydhub.com/api/v1/persons/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "person_kyd": "BOB.CARTER",
  "service_name": "acme-checkout",
  "fields": ["name"],
  "response_profile": "standard",
  "format": {
    "names": "given_first",
    "locale": "en-US",
    "include_raw": false
  }
}

{
  "person_kyd": "BOB.CARTER",
  "person_id": "per_7Q9M2K4R",
  "status": "success",
  "service_name": "acme-checkout",
  "response_profile_used": "standard",
  "format_used": {
    "names": "given_first",
    "addresses": "as_recorded",
    "text": "preserve",
    "dates": "iso",
    "locale": "en-US",
    "include_raw": false
  },
  "fields": {
    "name": {
      "formatted": "Bob Carter",
      "format_used": "given_first"
    }
  }
}

{
  "status": "error",
  "error": {
    "code": "data_grant_required",
    "message": "The service does not have an approved data grant to read the requested person fields.",
    "person_kyd": "BOB.CARTER",
    "service_name": "acme-checkout"
  }
}

QUERY https://dev.api.kydhub.com/api/v1/persons/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "person_kyd": "BOB.CARTER",
  "service_name": "acme-shipping",
  "fields": [
    "addresses.type",
    "addresses.city",
    "addresses.region",
    "addresses.country",
    "addresses.postal_code"
  ]
}

{
  "data": {
    "person_id": "per_7Q9M2K4R",
    "person_kyd": "BOB.CARTER",
    "fields": {
      "addresses": [
        {
          "type": "shipping",
          "city": "Buenos Aires",
          "region": "Ciudad Autónoma de Buenos Aires",
          "country": "AR",
          "postal_code": "C1000"
        }
      ]
    },
    "grant": {
      "status": "active",
      "scopes": ["person.addresses:read"]
    }
  }
}

{
  "person_id": "per_7Q9M2K4R",
  "service_name": "acme-shipping",
  "fields": ["addresses.city", "addresses.country"]
}

QUERY https://dev.api.kydhub.com/api/v1/companies/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "company_kyd": "ACME.SUPPLIER",
  "service_name": "acme-risk",
  "fields": ["identity", "profile", "locations"],
  "response_profile": "standard",
  "format": { "locale": "en-US" }
}

{
  "status": "success",
  "company_kyd": "ACME.SUPPLIER",
  "company_id": "comp_00000000-0000-4000-8000-000000000042",
  "service_name": "acme-risk",
  "response_profile_used": "standard",
  "fields": {
    "identity": {
      "company_kyd": "ACME.SUPPLIER",
      "company_id": "comp_00000000-0000-4000-8000-000000000042",
      "legal_name": "Acme Supplier LLC",
      "trade_name": "Acme Supplier",
      "country_code": "US",
      "profile_status": "complete",
      "is_active": true
    },
    "profile": {
      "website": "https://supplier.example",
      "logo_url": "https://cdn.example/supplier.svg",
      "activity_id": "activity-1"
    },
    "locations": [
      {
        "id": "loc-1",
        "name": "Headquarters",
        "type_name": "Office",
        "is_primary": true,
        "country_code": "US",
        "country_name": "United States",
        "postal_code": "33131",
        "address_detail": "1200 Brickell Ave",
        "reference": null,
        "latitude": 25.7617,
        "longitude": -80.1918
      }
    ]
  }
}

GET /api/v1/companies/{company_identifier}
GET /api/v1/companies/{company_identifier}/profile
GET /api/v1/companies/{company_identifier}/locations

QUERY https://dev.api.kydhub.com/api/v1/companies/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "company_kyd": "ACME.SUPPLIER",
  "service_name": "acme-supplier-review",
  "fields": [
    "locations.type",
    "locations.name",
    "locations.city",
    "locations.region",
    "locations.country"
  ]
}

{
  "data": {
    "company_id": "comp_00000000-0000-4000-8000-000000000042",
    "company_kyd": "ACME.SUPPLIER",
    "fields": {
      "locations": [
        {
          "type": "headquarters",
          "name": "Main office",
          "city": "Miami",
          "region": "Florida",
          "country": "US",
          "is_primary": true
        }
      ]
    },
    "scopes": ["company.locations:read"]
  }
}

{
  "company_id": "comp_00000000-0000-4000-8000-000000000042",
  "service_name": "acme-supplier-review",
  "fields": ["locations.city", "locations.country"]
}

# redirigí al usuario a KydHub
GET https://dev.auth.kydhub.com/oauth/authorize
  ?client_id=kh_client_…
  &redirect_uri=https://app.acme.example/callback
  &response_type=code
  &scope=openid kwid email profile company:read
  &state=RANDOM
  &code_challenge=…&code_challenge_method=S256

POST https://dev.auth.kydhub.com/oauth/login/start
Content-Type: application/json

{
  "client_id": "kh_client_…",
  "redirect_uri": "https://app.acme.example/callback",
  "scope": "openid kwid email profile company:read",
  "state": "RANDOM",
  "code_challenge": "…",
  "code_challenge_method": "S256",
  "verification_identifier": "BOB.CARTER"
}

{
  "data": {
    "status": "pending_verification",
    "login_attempt_id": "login_attempt_…",
    "expires_at": "2026-06-19T15:30:00Z",  // TTL 15 min
    "challenge_prefix": "abc12345"     // solo diagnóstico
  }
}

POST https://dev.auth.kydhub.com/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "kh_client_…",
  "client_secret": "CLIENT_SECRET_DEL_BACKEND",
  "code": "CODE_DEL_CALLBACK",
  "redirect_uri": "https://app.acme.example/callback",
  "code_verifier": "EL_VERIFIER_ORIGINAL"
}

{
  "access_token": "…",
  "id_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid kwid email profile company:read"
}

GET /userinfo
Authorization: Bearer ACCESS_TOKEN

{
  "sub": "person_01JDEVEXAMPLE",
  "kwid": "BOB.CARTER",
  "email": "bob.carter@example.test",
  "email_verified": true,
  "name": "Bob Carter",
  "given_name": "Bob",
  "family_name": "Carter",
  "picture": null
}

QUERY https://dev.api.kydhub.com/api/v1/persons/query
X-API-KEY: $KYDHUB_API_KEY
Content-Type: application/json

{
  "person_kyd": "BOB.CARTER",
  "service_name": "acme-checkout",
  "fields": ["person_id", "person_kyd", "name", "email"]
}

GET https://dev.api.kydhub.com/api/v1/companies/ACME.SUPPLIER
X-API-KEY: $KYDHUB_API_KEY

GET https://dev.api.kydhub.com/api/v1/companies/ACME.SUPPLIER/profile
X-API-KEY: $KYDHUB_API_KEY

GET https://dev.api.kydhub.com/api/v1/companies/ACME.SUPPLIER/locations?lang=es
X-API-KEY: $KYDHUB_API_KEY

POST https://app.acme.example/kydhub/webhook
X-KydHub-Event-Id: evt_01HVEXAMPLE
X-KydHub-Timestamp: 1760000000
X-KydHub-Signature-256: sha256=HEX_HMAC
Content-Type: application/json

{
  "id": "evt_01HVEXAMPLE",
  "type": "grant.approved",
  "created_at": "2026-06-28T12:00:00Z",
  "data": {
    "person_kyd": "BOB.CARTER",
    "company_id": "comp_00000000-0000-4000-8000-000000000042",
    "scopes": ["person.identity:read", "person.addresses:read"]
  }
}

import crypto from 'node:crypto';

function verifyKydHubWebhook(rawBody, signatureHeader, webhookSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

{
  "error": "field_not_allowed",
  "message": "One or more requested fields are not allowed for this API key or grant.",
  "fields": ["addresses.line1"]
}

{
  "error": "field_not_allowed",
  "message": "One or more requested fields are not allowed for this API key or grant.",
  "request_id": "req_01HVEXAMPLE",
  "fields": ["addresses.line1"]
}

{
  "product": "KydHub",
  "environment": "sandbox",
  "base_url": "https://dev.api.kydhub.com/api/v1",
  "auth": {
    "data_api": {
      "type": "api_key",
      "header": "X-API-KEY",
      "storage": "backend_or_secret_manager_only"
    },
    "oauth_oidc": {
      "optional": true,
      "issuer": "https://dev.kydhub.com",
      "flow": "authorization_code_pkce"
    }
  },
  "read_only_public_api": true,
  "examples": {
    "integrator_company": "Acme",
    "person_kyd": "BOB.CARTER",
    "company_kyd": "ACME.SUPPLIER",
    "person_id": "per_7Q9M2K4R",
    "company_id": "comp_00000000-0000-4000-8000-000000000042"
  }
}

{
  "protected_payload": {
    "alg": "KydHub-HybridPQ-MLKEM768-X25519-HKDF-AES256GCM",
    "kid": "kh_pq_key_2026_06",
    "kem_ciphertext": "BASE64URL_ML_KEM_CT",
    "ecdh_public_key": "BASE64URL_X25519_PUB",
    "nonce": "BASE64URL_96BIT",
    "ciphertext": "BASE64URL_AEAD_CT",
    "aad": "method=QUERY;path=/api/v1/persons/query;event=grant.approved"
  }
}