# Admin / Entities

This API suite is focused on managing identity entities within a system, allowing for their creation, retrieval, listing, and deletion. The entities are associated with cryptocurrency wallets or blockchain identities. All those APIs require an Admin authentication.

## Get the Admin status

<mark style="color:green;">`GET`</mark> `/api/v1/admin`

Use this API to confirm that the admin access is granted, and to get the host and agent locations.

**Headers**

| Name          | Value                             |
| ------------- | --------------------------------- |
| Content-Type  | `application/json`                |
| Authorization | `x-admin-api-key = <admin_token>` |

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": {
        "isAdmin": true,
        "host": "https://tom-g-jews-graduates.trycloudflare.com/",
        "agent": "https://tom-g-jews-graduates.trycloudflare.com/cloud-agent/"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Retrieves a list of identity entities

<mark style="color:green;">`GET`</mark> `/api/v1/admin/entities`

Retrieves list of entities created by Admin&#x20;

**Headers**

| Name          | Value                             |
| ------------- | --------------------------------- |
| Content-Type  | `application/json`                |
| Authorization | `x-admin-api-key = <admin_token>` |

**Body**

| Name   | Type   | Description      |
| ------ | ------ | ---------------- |
| `name` | string | Name of the user |
| `age`  | number | Age of the user  |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": [
        {
            "kind": "Entity",
            "self": "",
            "id": "e980fc11-c57d-490f-a0cc-004dfeb6b942",
            "name": "osais (admin)",
            "walletId": "8201a6f1-8eed-44f3-86e3-f505b238c6b7",
            "createdAt": "2024-06-14T17:49:33.108886Z",
            "updatedAt": "2024-06-14T17:49:33.108886Z"
        },
        {...}
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "statusText": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Retrieves information about a specific identity entity

<mark style="color:green;">`GET`</mark> `/api/v1/admin/entity/{entity}`

Retrieves a specific entity by id

**Headers**

| Name          | Value                             |
| ------------- | --------------------------------- |
| Content-Type  | `application/json`                |
| Authorization | `x-admin-api-key = <admin_token>` |

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": {
        "kind": "Entity",
        "self": "/iam/entities/e980fc11-c57d-490f-a0cc-004dfeb6b942",
        "id": "e980fc11-c57d-490f-a0cc-004dfeb6b942",
        "name": "osais (admin)",
        "walletId": "8201a6f1-8eed-44f3-86e3-f505b238c6b7",
        "createdAt": "2024-06-14T17:49:33.108886Z",
        "updatedAt": "2024-06-14T17:49:33.108886Z"
    }
}
```

{% endtab %}

{% tab title="401" %}

```
{
    "data": null,
    "status": 401,
    "statusText": "Unauthorized"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "data": null,
    "status": 404,
    "message": "Not found"
}
```

{% endtab %}
{% endtabs %}

## Create a new identity entity

<mark style="color:green;">`POST`</mark> `/api/v1/admin/entity`

Will create Entity, Wallet, Auth key, and Auth DID) ; note: a caller role will create a new wallet whereas any other role expects an id\_wallet passed in params

**Headers**

| Name          | Value                             |
| ------------- | --------------------------------- |
| Content-Type  | `application/json`                |
| Authorization | `x-admin-api-key = <admin_token>` |

**Body**

| Name        | Type   | Description                                                                    |
| ----------- | ------ | ------------------------------------------------------------------------------ |
| `name`      | string | Name for this wallet & entity                                                  |
| `role`      | string | A role for this entity (caller, worker, provider, admin)                       |
| `mnemonic`  | string | A seed phrase (optional ; if not provided, the API will generate a random one) |
| `id_wallet` | string | id of the existing wallet (then we do not use mnemonic)                        |

**Response**

{% tabs %}
{% tab title="201" %}

```json
{
    "data": {
        "id_entity": "d923cd74-b795-44cf-9f4a-6666e45daeef",
        "id_wallet": "5861593e-ce8d-4243-b4cd-610beb1bba94",
        "name": "snet",
        "role": "caller",
        "created_at": "2024-10-03T10:28:47.667Z",
        "key": "89990514e30f3cba48ac4adaec7c898c109de944a3df3a25eda4291ef8258c41",
        "public_addr": "addr_test1qqhr25v8d3gtxfvcu9p793hfhx3d2zkl7dkv9zl7yg84ctzm32sqdg9h5av4u7sey3x0psgdsa2utc78w6txhz4jfzdqtpqsjv",
        "longDid": "did:prism:53b0074c8fe0fef8082530021b11dd0facfabbf628907b05f57a82be96640104:CnoKeBI5CgVrZXktMRAESi4KCXNlY3AyNTZrMRIhAioRoqtz5wi9Ci70fp1sL1f99fXg4xo8CcCs-Ux6tPLpEjsKB21hc3RlcjAQAUouCglzZWNwMjU2azESIQNv-zBpfaBAdPavsP0GS4jz9tMYB9jYgcfX2IIPj7CNeg"
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "statusText": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Delete an existing entity

<mark style="color:green;">`DELETE`</mark> `/api/v1/admin/entity/{id_entity}`

Pass the correct id\_entity to delete the corresponding entity

**Headers**

| Name          | Value                             |
| ------------- | --------------------------------- |
| Content-Type  | `application/json`                |
| Authorization | `x-admin-api-key = <admin_token>` |

**Body**

**Response**

{% tabs %}
{% tab title="204" %}

```json
{}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "statusText": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}