Integrate with KYC
Resolve authoritative organization identity through the HTTP API or MCP.
KYC exposes one evidence-preserving workflow through two machine interfaces. Use the HTTP API from services and scheduled jobs. Use MCP when an agent or MCP-capable client needs the same search and get operations.
Choose an interface
| Interface | Endpoint | Best for |
|---|---|---|
| HTTP API | https://kyc.1above.ai/api/v1/* | Backend services, workflows, and direct request control |
| MCP | https://kyc.1above.ai/mcp | Agents and MCP clients with Streamable HTTP support |
Both interfaces use short-lived bearer JWTs minted by Identity, preserve the operating organization from the token, enforce the same product entitlements, and return a correlation ID for audit follow-up.
Before you start
Your Identity client needs access to the kyc-service audience and the read scope:
| Scope | Permission |
|---|---|
corporates:read | Search authoritative identity and get exact organization details |
Ask your Identity administrator to register or grant the client and operating organization. Store the resulting access token as KYC_ACCESS_TOKEN for the examples in these guides.
Bearer tokens only
Do not send a raw sk_* API key to KYC. API-key holders exchange that credential with Identity and call KYC with the short-lived bearer JWT they receive.
Obtain an access token
Identity publishes its OAuth and OIDC endpoints at https://identity.1above.io/.well-known/openid-configuration. Configure your registered client to use authorization code with PKCE S256, then request exactly one KYC resource indicator:
| Interface | Resource indicator |
|---|---|
| HTTP API | https://kyc.1above.ai |
| MCP | https://kyc.1above.ai/mcp |
Request openid, offline_access, and an explicitly granted corporates:read. Old lookup/enrichment grants are not aliases. Identity completes authorization at its published authorization endpoint and exchanges the code at its published token endpoint. The returned access token has the kyc-service audience and the operating organization selected during authorization.
For a backend workload, use the Identity credential flow approved for your operating organization. Client registration, organization access, and credential issuance are Identity administrator tasks; KYC does not issue credentials. Export only the resulting short-lived JWT:
export KYC_ACCESS_TOKEN='<identity-issued-access-token>'Search and exact get
Start with a strict search. Fuzzy candidates remain unresolved until an accountable request selects an exact registry identifier. Exact BRN search may return historical observed evidence without a current identity claim. Get retrieves authoritative details for an exact BRN; callers who already hold one may get directly. Only an entitled successful get may deliver an address, after durable address-free audit.