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. Start with a provisioned sandbox workspace and an initial operator or integration credential whose roles permit the setup steps. Signup provisions sandbox workspaces. Platform staff separately admit production enterprises with POST /enterprises, then run Provision enterprise to create the administrator, identity access, roles and commercial agreements. Admission alone does not complete provisioning.

Response examples come from the API contract. Replace sample identifiers with the identifiers returned by your own requests; examples show independent resources. See each linked endpoint for authentication, required headers, and error responses. Request lines use the production base URL, as the API reference does. In a sandbox workspace, send the same requests to https://b2b2x-sandbox.youhodler.com/api.

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 machine operations allowed by its role grants. Human decisions use a human access token instead.

Request URL

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

Request Body

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

Access token

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

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

2. Read your enterprise

GET /enterprises is a platform-wide staff operation. Tenant integrations read their own enterprise by ID, using the enterprise reference from their verified session or the b2b2x:tenant_ref claim.

Request URL

GET
GET https://b2b.youhodler.com/api/enterprises/<enterprise_id>

Enterprise

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

3. Provision a service account and grant access

A bare POST /service-accounts grants no permissions. Use the combined provisioning operation to create the account and bind an existing role, or create a role assignment for its service-accounts/<id> principal explicitly. The operator running provisioning needs service_accounts.create and role_assignments.create; choose a role and scope appropriate for the integration.

Request URL

POST
POST https://b2b.youhodler.com/api/service-accounts/provision

Request Body

application/json
{
  "description": "Withdrawal automation account",
  "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "roles": [
    {
      "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  ]
}

Provisioned service account

201 application/json
{
  "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "client_secret": "cs_live_abc123placeholder",
  "client_secret_expires_at": "2026-05-02T10:00:00Z",
  "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "role_assignment_errors": [],
  "role_assignments": [
    {
      "created_at": "2026-05-01T10:00:00Z",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "role_assignment",
      "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope_anchor_kind": "explicit",
      "scope_propagation": "subtree",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "active",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "service_account": {
    "description": "Withdrawal automation account",
    "created_at": "2026-05-01T10:00:00Z",
    "current_secret_expires_at": "2026-05-02T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "external_id": "sa-ext-001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "managed_by": null,
    "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "previous_secret_expires_at": null,
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "service_account",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
}

Store the returned secret securely: only this response carries it. A retry with the same Idempotency-Key and body returns the first response without client_secret and creates or grants nothing again. If the secret is lost, use secret rotation; neither a retry nor a new provisioning call recovers the original secret.

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://b2b.youhodler.com/api/users

Request Body

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

Request URL

POST
POST https://b2b.youhodler.com/api/role-assignments

Request Body

application/json
{
  "principal_ref": "users/44444444-4444-4444-8444-444444444444",
  "role_ref": "roles/55555555-5555-4555-8555-555555555555",
  "scope_ref": "enterprises/11111111-1111-4111-8111-111111111111",
  "scope_anchor_kind": "explicit",
  "scope_propagation": "subtree"
}

Created user

201 application/json
{
  "created_at": "2026-05-01T10:00:00Z",
  "display_name": "Jane Doe",
  "email": "jane.doe@acme.example",
  "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
  "federation": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "identity_source": "platform-managed",
  "resource": "human_actor",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "status": "active",
  "updated_at": "2026-05-01T10:00:00.000Z"
}

Granted role assignment

201 application/json
{
  "created_at": "2026-05-01T10:00:00Z",
  "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "resource": "role_assignment",
  "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "scope_anchor_kind": "explicit",
  "scope_propagation": "subtree",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "status": "active",
  "updated_at": "2026-05-01T10:00:00Z"
}

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

5. Define policies

Create a policy rule with POST /policy-rules. Each rule has one operation_type, an array of conditions, and a decision. The monetary threshold uses value; the decision's threshold is the number of approvals.

Request URL

POST
POST https://b2b.youhodler.com/api/policy-rules

Request Headers

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

Request Body

application/json
{
  "name": "Large crypto withdrawal approval",
  "description": "Require compliance review for large crypto withdrawals",
  "conditions": [
    {
      "amount_basis": "usd_equivalent",
      "kind": "amount_threshold",
      "operator": "gte",
      "threshold": {
        "currency": "USD",
        "value": "10000.00"
      }
    },
    {
      "asset_class": "crypto",
      "asset_role": "principal",
      "kind": "asset_class"
    }
  ],
  "decision": {
    "approver_role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiator_cannot_approve": true,
    "kind": "require_approval",
    "reason": "large_crypto_withdrawal",
    "threshold": 2
  },
  "operation_type": "withdrawal",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}

Creation returns a draft rule. Read the created rule's id and etag, then activate it before relying on it to govern operations:

Activate the rule

POST
POST https://b2b.youhodler.com/api/policy-rules/<rule_id>/activate
Authorization: Bearer <token>
If-Match: <etag from the rule>

See Activate policy rule for concurrency requirements. Approval resources are created by governed operations after the rule is active.