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
Request URL
POST https://b2b.youhodler.com/api/oauth/tokenRequest Body
{
"grant_type": "client_credentials",
"client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"client_secret": "replace-me"
}Access token
{
"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 https://b2b.youhodler.com/api/enterprises/<enterprise_id>Enterprise
{
"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 https://b2b.youhodler.com/api/service-accounts/provisionRequest Body
{
"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
{
"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
Request URL
POST https://b2b.youhodler.com/api/usersRequest Body
{
"email": "ops@acme.example",
"display_name": "Operations User",
"scope_ref": "enterprises/11111111-1111-4111-8111-111111111111"
}Request URL
POST https://b2b.youhodler.com/api/role-assignmentsRequest Body
{
"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
{
"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
{
"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 https://b2b.youhodler.com/api/policy-rulesRequest Headers
Authorization: Bearer <token>
Idempotency-Key: 6a4d4d14-b0f3-4d2d-a40f-9f6396d30360
Content-Type: application/jsonRequest Body
{
"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 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.