# Activation And Setup

> How to activate an enterprise tenant and set up identity, access, and the initial topology.

Source: https://business-api-docs.youhodler.com/docs/workflows/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.

> **Business impact:** After this sequence, the integration has an admitted enterprise perimeter, a service access path, human operators, authorization scope, and a policy surface ready for governed execution.

## 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.

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

[API Reference: Issue access token (POST)](/docs/api/reference/auth/oauth-token)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/oauth/token
```
**Request Body — application/json**
```json
{
  "grant_type": "client_credentials",
  "client_id": "sa-acme-admin",
  "client_secret": "replace-me"
}
```
**200 Success**

```json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

**401 Unauthorized**

```json
{
  "error": "unauthorized",
  "message": "Client authentication failed."
}
```

### 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.

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

[API Reference: List enterprises (GET)](/docs/api/reference/enterprises/enterprises-list)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/enterprises?page_size=20
```
**Request Body — application/json**
```json
{
  "legal_name": "Acme Treasury Ltd",
  "jurisdiction": "GB",
  "designated_admin": {
    "email": "admin@acme.example",
    "display_name": "Acme Admin"
  }
}
```
**200 Enterprise Page**

```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
}
```

**201 Enterprise Admitted**

```json
{
  "enterprise": {
    "id": "11111111-1111-4111-8111-111111111111",
    "resource": "enterprise",
    "legal_name": "Acme Treasury Ltd",
    "admission_state": "admitted",
    "restriction_state": "open",
    "jurisdiction": "GB"
  },
  "master_account": {
    "id": "22222222-2222-4222-8222-222222222222",
    "resource": "master-account",
    "owner": "enterprises/11111111-1111-4111-8111-111111111111",
    "display_name": "Acme Primary Treasury"
  },
  "bootstrap_principal": {
    "id": "33333333-3333-4333-8333-333333333333",
    "resource": "service-account"
  }
}
```

### 3. Create service accounts

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

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

[API Reference: Create service account (POST)](/docs/api/reference/service-accounts/service-accounts-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/service-accounts
```
**Request Body — application/json**
```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"
}
```
**201 Service Account Created**

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

**409 Conflict**

```json
{
  "error": "state_conflict",
  "message": "A matching service account already exists for the requested profile."
}
```

### 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.

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

[API Reference: Create user (POST)](/docs/api/reference/users/users-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/users
```
**Request Body — application/json**
```json
{
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "email": "ops@acme.example",
  "display_name": "Operations User"
}
```
**Request Body — application/json**
```json
{
  "principal": "users/44444444-4444-4444-8444-444444444444",
  "role": "roles/55555555-5555-4555-8555-555555555555",
  "scope": "enterprises/11111111-1111-4111-8111-111111111111"
}
```
**201 User Created**

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

**201 Role Assignment Granted**

```json
{
  "id": "66666666-6666-4666-8666-666666666666",
  "resource": "role-assignment",
  "principal": "users/44444444-4444-4444-8444-444444444444",
  "role": "roles/55555555-5555-4555-8555-555555555555",
  "scope": "enterprises/11111111-1111-4111-8111-111111111111",
  "status": "active"
}
```

### 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.

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

[API Reference: Create policy (POST)](/docs/api)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/policies
```
**Request Headers — required**
```json
Authorization: Bearer <token>
Idempotency-Key: 6a4d4d14-b0f3-4d2d-a40f-9f6396d30360
Content-Type: application/json
```
**Request Body — application/json**
```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"
      }
    }
  ]
}
```
**201 Policy Created**

```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\""
}
```

**409 Conflict**

```json
{
  "error": "state_conflict",
  "message": "A policy with the same name already exists within the requested scope."
}
```