# Account linking

9 management API operations.

- [POST /v1/link-challenges](/docs/api/operations/create_challenge_v1_link_challenges_post): Create Challenge
- [GET /v1/link-challenges/{challenge_id}](/docs/api/operations/read_challenge_v1_link_challenges__challenge_id__get): Read Challenge
- [POST /v1/link-challenges/{challenge_id}/attest](/docs/api/operations/attest_v1_link_challenges__challenge_id__attest_post): Attest
- [GET /v1/link-requests/{link_id}](/docs/api/operations/read_link_v1_link_requests__link_id__get): Read Link
- [POST /v1/link-requests/{link_id}/ack](/docs/api/operations/acknowledge_v1_link_requests__link_id__ack_post): Acknowledge
- [GET /v1/projects/{project_id}/service-identities](/docs/api/operations/read_services_v1_projects__project_id__service_identities_get): Read Services
- [POST /v1/projects/{project_id}/service-identities](/docs/api/operations/propose_service_v1_projects__project_id__service_identities_post): Propose Service
- [POST /v1/projects/{project_id}/service-identities/{grant_id}/approve](/docs/api/operations/approve_service_v1_projects__project_id__service_identities__grant_id__approve_post): Approve Service
- [POST /v1/projects/{project_id}/service-identities/{grant_id}/revoke](/docs/api/operations/revoke_service_v1_projects__project_id__service_identities__grant_id__revoke_post): Revoke Service

## POST /v1/link-challenges

Create Challenge

Create Challenge

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 |
| --- | --- | --- | --- | --- |
| `idempotency-key` | header | string | Yes |  |

### Request body

#### application/json

Required; ChallengeCreate

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |
| `project_id` |  | string | Yes |  |
| `institution_id` |  | string | Yes |  |

### Responses

#### 201

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X POST 'https://YOUR_IDENTITY_HOST/v1/link-challenges' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON",
  "project_id": "REPLACE_WITH_PROJECT_ID",
  "institution_id": "REPLACE_WITH_INSTITUTION_ID"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/link-challenges', {
  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",
  "project_id": "REPLACE_WITH_PROJECT_ID",
  "institution_id": "REPLACE_WITH_INSTITUTION_ID"
})
});

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

#### Python

```python
import os
import json
import requests

response = requests.request(
    'POST',
    'https://YOUR_IDENTITY_HOST/v1/link-challenges',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON","project_id":"REPLACE_WITH_PROJECT_ID","institution_id":"REPLACE_WITH_INSTITUTION_ID"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/create_challenge_v1_link_challenges_post)

## GET /v1/link-challenges/{challenge_id}

Read Challenge

Read Challenge

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 |
| --- | --- | --- | --- | --- |
| `challenge_id` | path | string | Yes |  |

### Request body

This operation has no request body.

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X GET 'https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.TAIFA_MANAGEMENT_TOKEN}`
  }
});

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

#### Python

```python
import os
import requests

response = requests.request(
    'GET',
    'https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN']}
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/read_challenge_v1_link_challenges__challenge_id__get)

## POST /v1/link-challenges/{challenge_id}/attest

Attest

Attest

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 |
| --- | --- | --- | --- | --- |
| `challenge_id` | path | string | Yes |  |
| `idempotency-key` | header | string | Yes |  |

### Request body

#### application/json

Required; Attestation

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |
| `local_account_id` |  | string | Yes | Validation: min length 1; max length 200 |
| `local_auth_time` |  | integer | Yes |  |
| `local_auth_method` |  | string | Yes | Validation: min length 1; max length 100 |
| `local_session_digest` |  | string | Yes | Validation: pattern ^[0-9a-f]{64}$ |
| `central_issuer` |  | string | Yes |  |
| `central_subject` |  | string | Yes |  |
| `central_auth_time` |  | integer | Yes |  |
| `central_acr` |  | taifa-mfa \| taifa-phishing-resistant | Yes |  |
| `central_sid_digest` |  | string | Yes | Validation: pattern ^[0-9a-f]{64}$ |

### Responses

#### 201

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X POST 'https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID/attest' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON",
  "local_account_id": "REPLACE_WITH_LOCAL_ACCOUNT_ID",
  "local_auth_time": 0,
  "local_auth_method": "REPLACE_WITH_LOCAL_AUTH_METHOD",
  "local_session_digest": "REPLACE_WITH_LOCAL_SESSION_DIGEST",
  "central_issuer": "REPLACE_WITH_CENTRAL_ISSUER",
  "central_subject": "REPLACE_WITH_CENTRAL_SUBJECT",
  "central_auth_time": 0,
  "central_acr": "REPLACE_WITH_CENTRAL_ACR",
  "central_sid_digest": "REPLACE_WITH_CENTRAL_SID_DIGEST"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID/attest', {
  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",
  "local_account_id": "REPLACE_WITH_LOCAL_ACCOUNT_ID",
  "local_auth_time": 0,
  "local_auth_method": "REPLACE_WITH_LOCAL_AUTH_METHOD",
  "local_session_digest": "REPLACE_WITH_LOCAL_SESSION_DIGEST",
  "central_issuer": "REPLACE_WITH_CENTRAL_ISSUER",
  "central_subject": "REPLACE_WITH_CENTRAL_SUBJECT",
  "central_auth_time": 0,
  "central_acr": "REPLACE_WITH_CENTRAL_ACR",
  "central_sid_digest": "REPLACE_WITH_CENTRAL_SID_DIGEST"
})
});

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

#### Python

```python
import os
import json
import requests

response = requests.request(
    'POST',
    'https://YOUR_IDENTITY_HOST/v1/link-challenges/REPLACE_WITH_CHALLENGE_ID/attest',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON","local_account_id":"REPLACE_WITH_LOCAL_ACCOUNT_ID","local_auth_time":0,"local_auth_method":"REPLACE_WITH_LOCAL_AUTH_METHOD","local_session_digest":"REPLACE_WITH_LOCAL_SESSION_DIGEST","central_issuer":"REPLACE_WITH_CENTRAL_ISSUER","central_subject":"REPLACE_WITH_CENTRAL_SUBJECT","central_auth_time":0,"central_acr":"REPLACE_WITH_CENTRAL_ACR","central_sid_digest":"REPLACE_WITH_CENTRAL_SID_DIGEST"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/attest_v1_link_challenges__challenge_id__attest_post)

## GET /v1/link-requests/{link_id}

Read Link

Read Link

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 |
| --- | --- | --- | --- | --- |
| `link_id` | path | string | Yes |  |

### Request body

This operation has no request body.

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X GET 'https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.TAIFA_MANAGEMENT_TOKEN}`
  }
});

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

#### Python

```python
import os
import requests

response = requests.request(
    'GET',
    'https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN']}
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/read_link_v1_link_requests__link_id__get)

## POST /v1/link-requests/{link_id}/ack

Acknowledge

Acknowledge

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 |
| --- | --- | --- | --- | --- |
| `link_id` | path | string | Yes |  |
| `idempotency-key` | header | string | Yes |  |

### Request body

#### application/json

Required; BindingAcknowledgement

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |
| `entity_id` |  | string | Yes |  |
| `entity_version` |  | integer | Yes | Validation: minimum 1 |
| `local_account_id` |  | string | Yes |  |
| `proof_id` |  | string | Yes |  |
| `approval_id` |  | string | Yes |  |

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X POST 'https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID/ack' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON",
  "entity_id": "REPLACE_WITH_ENTITY_ID",
  "entity_version": 0,
  "local_account_id": "REPLACE_WITH_LOCAL_ACCOUNT_ID",
  "proof_id": "REPLACE_WITH_PROOF_ID",
  "approval_id": "REPLACE_WITH_APPROVAL_ID"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID/ack', {
  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",
  "entity_id": "REPLACE_WITH_ENTITY_ID",
  "entity_version": 0,
  "local_account_id": "REPLACE_WITH_LOCAL_ACCOUNT_ID",
  "proof_id": "REPLACE_WITH_PROOF_ID",
  "approval_id": "REPLACE_WITH_APPROVAL_ID"
})
});

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

#### Python

```python
import os
import json
import requests

response = requests.request(
    'POST',
    'https://YOUR_IDENTITY_HOST/v1/link-requests/REPLACE_WITH_LINK_ID/ack',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON","entity_id":"REPLACE_WITH_ENTITY_ID","entity_version":0,"local_account_id":"REPLACE_WITH_LOCAL_ACCOUNT_ID","proof_id":"REPLACE_WITH_PROOF_ID","approval_id":"REPLACE_WITH_APPROVAL_ID"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/acknowledge_v1_link_requests__link_id__ack_post)

## GET /v1/projects/{project_id}/service-identities

Read Services

Read Services

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

### Request body

This operation has no request body.

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### Request examples

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

#### cURL

```sh
curl -X GET 'https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.TAIFA_MANAGEMENT_TOKEN}`
  }
});

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

#### Python

```python
import os
import requests

response = requests.request(
    'GET',
    'https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN']}
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/read_services_v1_projects__project_id__service_identities_get)

## POST /v1/projects/{project_id}/service-identities

Propose Service

Propose Service

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; ServiceProposal

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |
| `issuer` |  | string | Yes |  |
| `subject` |  | string | Yes | Validation: min length 1; max length 255 |
| `capability` |  | account-link-attestor | Yes |  |

### Responses

#### 201

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### 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/service-identities' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON",
  "issuer": "REPLACE_WITH_ISSUER",
  "subject": "REPLACE_WITH_SUBJECT",
  "capability": "REPLACE_WITH_CAPABILITY"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities', {
  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",
  "issuer": "REPLACE_WITH_ISSUER",
  "subject": "REPLACE_WITH_SUBJECT",
  "capability": "REPLACE_WITH_CAPABILITY"
})
});

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/service-identities',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON","issuer":"REPLACE_WITH_ISSUER","subject":"REPLACE_WITH_SUBJECT","capability":"REPLACE_WITH_CAPABILITY"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/propose_service_v1_projects__project_id__service_identities_post)

## POST /v1/projects/{project_id}/service-identities/{grant_id}/approve

Approve Service

Approve Service

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 |  |
| `grant_id` | path | string | Yes |  |
| `idempotency-key` | header | string | Yes |  |

### Request body

#### application/json

Required; Mutation

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### 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/service-identities/REPLACE_WITH_GRANT_ID/approve' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities/REPLACE_WITH_GRANT_ID/approve', {
  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"
})
});

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/service-identities/REPLACE_WITH_GRANT_ID/approve',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/approve_service_v1_projects__project_id__service_identities__grant_id__approve_post)

## POST /v1/projects/{project_id}/service-identities/{grant_id}/revoke

Revoke Service

Revoke Service

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 |  |
| `grant_id` | path | string | Yes |  |
| `idempotency-key` | header | string | Yes |  |

### Request body

#### application/json

Required; Mutation

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `reason` |  | string | Yes | Validation: min length 8; max length 500 |

### Responses

#### 200

Successful Response

No fields declared in the current specification.

#### 422

Validation Error

| Field | Variant | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `detail` |  | ValidationError[] | No |  |

### 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/service-identities/REPLACE_WITH_GRANT_ID/revoke' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "reason": "REPLACE_WITH_REASON"
}'
```

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

```typescript
const response = await fetch('https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/service-identities/REPLACE_WITH_GRANT_ID/revoke', {
  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"
})
});

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/service-identities/REPLACE_WITH_GRANT_ID/revoke',
    headers={'Authorization': 'Bearer ' + os.environ['TAIFA_MANAGEMENT_TOKEN'], 'idempotency-key': 'REPLACE_WITH_IDEMPOTENCY_KEY'},
    json=json.loads('{"reason":"REPLACE_WITH_REASON"}')
)
response.raise_for_status()
```

### Response example

No response example in the current specification.


[Request and response examples](/docs/api/operations/revoke_service_v1_projects__project_id__service_identities__grant_id__revoke_post)