Access And Topology

This group covers the entry point into the public API and the root tenant boundary. Read these methods in perimeter order: authenticate first, discover or admit the enterprise second, then inspect the enterprise-owned financial boundary through master accounts.

Access And Perimeter

Issue access token

Server-side entry point. Every backend integration begins by issuing a bearer token through the client-credentials flow. Nothing else in this group is readable until that access path exists.

Request URL

POST
POST https://b2b.youhodler.com/api/oauth/token

Request Body

application/json
{
  "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "client_secret": "cs_live_abc123placeholder",
  "grant_type": "client_credentials"
}

Response

application/json
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiOGUyZjFhMCJ9.sig",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer"
}

List enterprises

Perimeter discovery. List enterprises when the integration needs to confirm which tenant roots already exist and which admission states are currently active.

Request URL

GET
GET https://b2b.youhodler.com/api/enterprises?page_size=20

Response

application/json
{
  "items": [
    {
      "admission_state": "operational",
      "created_at": "2026-05-01T10:00:00Z",
      "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "etag": "2026-05-01T10:00:00.000Z",
      "external_id": "ent-ext-0001",
      "first_access_method": "enterprise_idp",
      "iam_hosting": "platform",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "jurisdiction": "DE",
      "jurisdiction_selected": true,
      "kyb_source": "sumsub",
      "kyb_stage": "verified",
      "kyb_state": "verified",
      "kyb_state_reason": null,
      "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
      "kyc_source": null,
      "kyc_stage": null,
      "legal_form": "GmbH",
      "legal_name": "Acme Fintech GmbH",
      "metadata": {
        "hq_country": "DE",
        "industry": "fintech"
      },
      "resource": "enterprise",
      "restriction_kind": null,
      "restriction_reason": null,
      "restriction_state": "none",
      "terminated_at": null,
      "termination_reason": null,
      "updated_at": "2026-05-01T10:00:00.000Z"
    }
  ],
  "next_page_token": null
}

Get enterprise

Single-tenant read. Read one enterprise when later setup work needs the exact tenant root, its lifecycle posture, or its current perimeter metadata.

Request URL

GET
GET https://b2b.youhodler.com/api/enterprises/11111111-1111-4111-8111-111111111111

Response

application/json
{
  "admission_state": "operational",
  "created_at": "2026-05-01T10:00:00Z",
  "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "etag": "2026-05-01T10:00:00.000Z",
  "external_id": "ent-ext-0001",
  "first_access_method": "enterprise_idp",
  "iam_hosting": "platform",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "jurisdiction": "DE",
  "jurisdiction_selected": true,
  "kyb_stage": "verified",
  "kyb_state": "verified",
  "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
  "kyc_stage": null,
  "legal_form": "GmbH",
  "legal_name": "Acme Fintech GmbH",
  "metadata": {
    "hq_country": "DE",
    "industry": "fintech"
  },
  "resource": "enterprise",
  "restriction_kind": null,
  "restriction_reason": null,
  "restriction_state": "none",
  "terminated_at": null,
  "termination_reason": null,
  "updated_at": "2026-05-01T10:00:00.000Z"
}

List master accounts

Root financial boundary. Inspect master accounts once the enterprise perimeter is known. This is the top-level operating account layer used for enterprise liquidity and root balance visibility.

Request URL

GET
GET https://b2b.youhodler.com/api/master-accounts?scope_ref=enterprises/11111111-1111-4111-8111-111111111111

Response

application/json
{
  "items": [
    {
      "created_at": "2026-05-01T10:00:00Z",
      "display_name": "Primary Settlement Account",
      "etag": "2026-05-01T10:00:00.000Z",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "master_account",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "active",
      "tenant_type": "enterprise",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "next_page_token": null
}