# Request controlled custody for a proposed owned-client credential

POST /v1/projects/{project_id}/owned-clients/credential-intents

A current approved project owner with exact active sponsorship and recent strong authentication records an audited, short-lived intent for the configured runtime. Idempotency-Key scopes retries to the exact actor and body. This response contains only the intent ID and pending custody status. Controlled private delivery and independent registration review remain required.

Authentication: bearer access token with audience `taifa-management`. Endpoint roles and eligibility are reviewed separately from the OpenAPI bearer scheme.

No operation-specific scopes are declared in the OpenAPI document. Bearer authentication and endpoint authorization requirements still apply.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `project_id` | path | string | Yes |  |
| `idempotency-key` | header | string | Yes |  |

## Request body

### application/json

Required; IntentRequest

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Trimmed printable reason recorded in the accepted Audit Validation: min length 8; max length 500 |
| `client_id` |  | string | Yes | Exact client ID for the proposed registration Validation: min length 1; max length 128 |
| `client_version` |  | integer | Yes | Proposed registration version, greater than approved history Validation: minimum 1; maximum 9223372036854775807 |
| `destination_runtime` |  | string | Yes | Exact locally configured custody runtime Validation: min length 1; max length 128 |

## Responses

### 201

Successful Response

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` |  | string · uuid | Yes | Server-generated canonical intent UUID |
| `custody_status` |  | pending | Yes | Awaiting controlled private custody delivery |

### 400

Empty or oversized idempotency key

No fields declared in the current specification.

### 401

Workforce authentication required

No fields declared in the current specification.

### 403

Current owner, sponsorship or recent strong authentication required

No fields declared in the current specification.

### 409

Ambiguous sponsorship, client/version binding or concurrent authority conflict

No fields declared in the current specification.

### 410

Original replayed intent expired, cancelled or authority revoked

No fields declared in the current specification.

### 422

Missing required fields or header, invalid exact payload or audit reason

No fields declared in the current specification.

### 503

Disabled custody source or current local key profile unavailable

No fields declared in the current specification.

## Request examples

Illustrative only. Replace placeholders and keep management tokens on the server.

### cURL

```sh
curl -X POST 'https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/owned-clients/credential-intents' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON",
  "client_id": "REPLACE_WITH_CLIENT_ID",
  "client_version": 0,
  "destination_runtime": "REPLACE_WITH_DESTINATION_RUNTIME"
}'
```

### TypeScript (Node.js/server-side)

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/owned-clients/credential-intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAIFA_MANAGEMENT_TOKEN}`,
    'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "reason": "REPLACE_WITH_REASON",
  "client_id": "REPLACE_WITH_CLIENT_ID",
  "client_version": 0,
  "destination_runtime": "REPLACE_WITH_DESTINATION_RUNTIME"
})
});

const result = await response.json();
```

### Python

```python
import os
import json
import requests

response = requests.request(
    'POST',
    'https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/owned-clients/credential-intents',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON","client_id":"REPLACE_WITH_CLIENT_ID","client_version":0,"destination_runtime":"REPLACE_WITH_DESTINATION_RUNTIME"}')
)
response.raise_for_status()
```

## Response example

No response example in the current specification.