YOUHODLERBusiness API
Get access
View as Markdown

Activation And Setup

Start with enterprise perimeter, actor access, and governance.

Read this page as the shortest operational path from token issuance to a usable enterprise control plane. Each step includes the exact request and response shape you need before opening the full API contract page.

Operational Sequence

1. Issue an access token

OAuth client credentials. Start every server-side integration with token issuance. This establishes the bearer token used by all later control-plane requests.

Request URL

POST
POST https://business-api.youhodler.com/oauth/token

Request Body

application/json
{
  "grant_type": "client_credentials",
  "client_id": "sa-acme-admin",
  "client_secret": "replace-me"
}

Response

application/json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
postAPI Reference: Issue access token

Use the access token from this response as the Authorization bearer token in the next steps.

2. Read or admit the enterprise

Tenant topology boundary. Confirm the enterprise perimeter first. This is the root boundary for identities, clients, policies, balances, and downstream operations.

Request URL

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

Request Body

application/json
{
  "legal_name": "Acme Treasury Ltd",
  "jurisdiction": "GB",
  "designated_admin": {
    "email": "admin@acme.example",
    "display_name": "Acme Admin"
  }
}

Response

application/json
{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "resource": "enterprise",
      "legal_name": "Acme Treasury Ltd",
      "admission_state": "admitted",
      "restriction_state": "open",
      "jurisdiction": "GB",
      "created_at": "2026-04-28T12:34:56.000Z",
      "updated_at": "2026-04-28T12:34:56.000Z",
      "etag": "W/\"enterprise-1\""
    }
  ],
  "next_page_token": null
}
getAPI Reference: List enterprises

If the enterprise already exists, read it. If the perimeter is not admitted yet, create it explicitly.

3. Create service accounts

Backend access. Use service accounts for server-side automation, ingestion, and operational execution that should not depend on human sessions.

Request URL

POST
POST https://business-api.youhodler.com/service-accounts

Request Body

application/json
{
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "capabilities": [
    "users.read",
    "users.write",
    "policies.read",
    "policies.write"
  ],
  "scope": [
    {
      "target": "enterprises/11111111-1111-4111-8111-111111111111",
      "extent": "perimeter"
    }
  ],
  "profile": "backend-integration"
}

Response

application/json
{
  "service_account": {
    "id": "33333333-3333-4333-8333-333333333333",
    "resource": "service-account",
    "parent": "enterprises/11111111-1111-4111-8111-111111111111",
    "status": "active",
    "profile": "backend-integration",
    "capabilities": [
      "users.read",
      "users.write",
      "policies.read",
      "policies.write"
    ]
  },
  "one_time_secret": "sp-secret-once-only",
  "secret_expires_at": "2026-04-28T12:49:56.000Z"
}
postAPI Reference: Create service account

The one-time secret is only returned at creation time. Persist it securely before moving on.

4. Create users and assign roles

Operator access model. Add human actors for setup and review, then bind them to roles and role assignments so capability scope is explicit.

Request URL

POST
POST https://business-api.youhodler.com/users

Request Body

application/json
{
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "email": "ops@acme.example",
  "display_name": "Operations User"
}

Request Body

application/json
{
  "principal": "users/44444444-4444-4444-8444-444444444444",
  "role": "roles/55555555-5555-4555-8555-555555555555",
  "scope": "enterprises/11111111-1111-4111-8111-111111111111"
}

Response

application/json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "resource": "user",
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "email": "ops@acme.example",
  "display_name": "Operations User",
  "status": "active",
  "identity_source": "platform-managed"
}
postAPI Reference: Create user

This step usually combines three operations in sequence: create the user, create or choose a role, then grant the role assignment.

5. Define policies

Execution controls. Establish policy constraints before enabling live financial execution. Approval resources are then created by governed runtime flows, not manually seeded in advance.

Request URL

POST
POST https://business-api.youhodler.com/policies

Request Headers

required
Authorization: Bearer <token>
Idempotency-Key: 6a4d4d14-b0f3-4d2d-a40f-9f6396d30360
Content-Type: application/json

Request Body

application/json
{
  "name": "enterprise-withdrawal-review",
  "scope_ref": "enterprises/11111111-1111-4111-8111-111111111111",
  "rules": [
    {
      "kind": "require-approval",
      "operation_types": [
        "withdrawal"
      ],
      "threshold": {
        "amount": "10000.00",
        "currency": "USD"
      }
    }
  ]
}

Response

application/json
{
  "id": "77777777-7777-4777-8777-777777777777",
  "resource": "policy",
  "name": "enterprise-withdrawal-review",
  "status": "active",
  "scope_ref": "enterprises/11111111-1111-4111-8111-111111111111",
  "rules": [
    {
      "kind": "require-approval",
      "operation_types": [
        "withdrawal"
      ],
      "threshold": {
        "amount": "10000.00",
        "currency": "USD"
      }
    }
  ],
  "created_at": "2026-04-28T12:34:56.000Z",
  "updated_at": "2026-04-28T12:34:56.000Z",
  "etag": "W/\"policy-1\""
}
postAPI Reference: Create policy

Policy scope can be topology-scoped or account-scoped. For enterprise-wide control, start with a topology-scoped rule set.