# Organization API keys (Beta)

{% hint style="info" %}
The following endpoints are available in the v0.4 Alphamoon Workspace REST API (BETA).
{% endhint %}

## Create organization API key

To create an organization API key (Admin only), use the following endpoint:

<mark style="color:blue;">`POST`</mark> `/api/v0.4/admin/api-keys`

**Request body example:**

```json
{
  "name": "TEST API key",
  "exp": "2024-07-17T07:23:51.104Z",
  "scopes": [
    "workspace.collection:create"
  ]
}
```

Make sure you:

* Enter the **name of your API key,**&#x20;
* Set the **API key expiration date** (we recommend changing the API key every 3 to 6 months),
* Enter the [**organization** **API scopes**](#organization-api-scopes).

{% tabs %}
{% tab title="201: OK  Successful Response" %}

```json
{
  "id": "31b7de83bfa24a9dbf2150beb5e5660b",
  "name": "TEST API key",
  "orgId": "USER:google-oauth2|123456789123456789123",
  "scopes": [
    "workspace.collection:create"
  ],
  "status": "Active",
  "createdAt": "2024-05-17T07:25:33Z",
  "exp": "2024-07-17T07:23:51Z",
  "key": "your_api_key_here"
}
```

{% endtab %}

{% tab title="400: Bad request" %}

```json
{
  "action": "The client should not repeat this request without modification.",
  "detail": "Please see the 'errors' field for details.",
  "errors": [
    {
      "location": "body: priority",
      "message": "field required",
      "type": "request_validation_error"
    }
  ],
  "instance": "30e18f59-7c88-4e25-9bed-61863b2abf4b",
  "status": 400,
  "timestamp": "2021-11-09T17:43:36Z",
  "title": "The server cannot process the request due to a client error.",
  "type": "RequestValidationError"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="API call" %}

```bash
curl -X 'POST' \
  'https://workspace.alphamoon.ai/api/v0.4/admin/api-keys' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "TEST API key",
  "exp": "2024-07-17T07:23:51.104Z",
  "scopes": [
    "workspace.collection:create"
  ]
}'
```

{% endtab %}

{% tab title="Server response" %}

```json
{
  "id": "31b7de83bfa24a9dbf2150beb5e5660b",
  "name": "TEST API key",
  "orgId": "USER:google-oauth2|123456789123456789123",
  "scopes": [
    "workspace.collection:create"
  ],
  "status": "Active",
  "createdAt": "2024-05-17T07:25:33Z",
  "exp": "2024-07-17T07:23:51Z",
  "key": "your_api_key_here"
}
```

{% endtab %}
{% endtabs %}

## Get API keys

Use the endpoint below to get your organization API keys:

<mark style="color:blue;">`GET`</mark> `/api/v0.4/admin/api-keys`

**Parameters**

| Name   | Type  | Description                                      |
| ------ | ----- | ------------------------------------------------ |
| offset | query | The number of elements to skip                   |
| limit  | query | The maximum number of elements to return at once |

{% tabs %}
{% tab title="200: OK Successful Response  " %}

```json
{
  "apiKeys": [
    {
      "id": "9c75da7200264beb91ffe05912591e46",
      "name": "NEW API key",
      "orgId": "USER:google-oauth2|123456789123456789123",
      "scopes": [
        "workspace.admin.user:read",
        "workspace.collection:update",
        "workspace.admin.process:manage",
        "workspace.collection:delete",
        "workspace.process.api_key:manage",
        "workspace.file:download",
        "workspace.export:delete",
        "workspace.result:read",
        "workspace.destination:delete",
        "workspace.process:read",
        "workspace.process:create",
        "workspace.admin.collection:manage",
        "workspace.admin.api_key:manage",
        "workspace.export:create",
        "workspace.destination:read",
        "workspace.collection:read",
        "workspace.admin.user:invite",
        "workspace.result:create",
        "workspace.process:update",
        "workspace.file:upload",
        "workspace.result:delete",
        "workspace.process:delete",
        "workspace.admin.user:manage",
        "workspace.result:update",
        "workspace.collection:create",
        "workspace.destination:create",
        "workspace.admin.subscriptions:manage"
      ],
      "status": "Active",
      "createdAt": "2024-05-17T07:23:03Z",
      "exp": "2024-07-31T21:59:59Z"
    },
    {
      "id": "31b7de83bfa27a9dbf2150beb5e5660b",
      "name": "TEST API key",
      "orgId": "USER:google-oauth2|123456789123456789123",
      "scopes": [
        "workspace.collection:create"
      ],
      "status": "Active",
      "createdAt": "2024-05-17T07:25:33Z",
      "exp": "2024-07-17T07:23:51Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 2
  }
}
```

{% endtab %}

{% tab title="422: Validation error" %}

```json
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

#### See the example:

{% tabs %}
{% tab title="API call" %}

```bash
curl -X 'GET' \
  'https://workspace.alphamoon.ai/api/v0.4/admin/api-keys?offset=0&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED'
```

{% endtab %}

{% tab title="Server response" %}

```json
{
  "apiKeys": [
    {
      "id": "9c75da72002645ea91ffe05912591e46",
      "name": "NEW API key",
      "orgId": "USER:google-oauth2|123456789123456789123",
      "scopes": [
        "workspace.admin.user:read",
        "workspace.collection:update",
        "workspace.admin.process:manage",
        "workspace.collection:delete",
        "workspace.process.api_key:manage",
        "workspace.file:download",
        "workspace.export:delete",
        "workspace.result:read",
        "workspace.destination:delete",
        "workspace.process:read",
        "workspace.process:create",
        "workspace.admin.collection:manage",
        "workspace.admin.api_key:manage",
        "workspace.export:create",
        "workspace.destination:read",
        "workspace.collection:read",
        "workspace.admin.user:invite",
        "workspace.result:create",
        "workspace.process:update",
        "workspace.file:upload",
        "workspace.result:delete",
        "workspace.process:delete",
        "workspace.admin.user:manage",
        "workspace.result:update",
        "workspace.collection:create",
        "workspace.destination:create",
        "workspace.admin.subscriptions:manage"
      ],
      "status": "Active",
      "createdAt": "2024-05-17T07:23:03Z",
      "exp": "2024-07-31T21:59:59Z"
    },
    {
      "id": "31b7de83bfa24a9dbf2150beb5e5660b",
      "name": "TEST API key",
      "orgId": "USER:google-oauth2|123456789123456789123",
      "scopes": [
        "workspace.collection:create"
      ],
      "status": "Active",
      "createdAt": "2024-05-17T07:25:33Z",
      "exp": "2024-07-17T07:23:51Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 2
  }
}
```

{% endtab %}
{% endtabs %}

## Delete an API key

The endpoint below enables you to delete an API key using its ID.

<mark style="color:red;">`DELETE`</mark> `/api/v0.4/admin/api-keys/{api-key-id}`

**Parameters**

| Name                                           | Type   | Description                              |
| ---------------------------------------------- | ------ | ---------------------------------------- |
| api\_key\_id<mark style="color:red;">\*</mark> | string | The ID of the API key you want to delete |

{% tabs %}
{% tab title="204: OK Successful Response" %}

```json
"string"
```

{% endtab %}

{% tab title="422: Validation error" %}

```json
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

\
**See the example:**

{% tabs %}
{% tab title="API call" %}

```bash
curl -X 'DELETE' \
  'https://workspace.alphamoon.ai/api/v0.4/admin/api-keys/31b7de83bfa24a9dbf2150beb5e5660b' \
  -H 'accept: */*' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED'
```

{% endtab %}

{% tab title="Server response" %}

```json
"string"
```

{% endtab %}
{% endtabs %}

## Organization API scopes

### Collections & images

The following API scopes allow users to manage collections of files in Alphamoon, including uploading, organizing, deleting, and updating existing collections.

<table><thead><tr><th width="361">Scope</th><th width="302">Description</th></tr></thead><tbody><tr><td>"workspace.collection:create"</td><td>Grants access to create new collections of files.</td></tr><tr><td>"workspace.collection:read"</td><td>Lists collections in the processes, display collections.</td></tr><tr><td>"workspace.collection:update"</td><td>Grants access to update collections of files.</td></tr><tr><td>"workspace.collection:delete"</td><td>Grants access to delete collections of files.</td></tr><tr><td>"workspace.collection_editor:override"</td><td>Grants access to make changes to existing collections.</td></tr></tbody></table>

### Files & documents

The API scopes below provide access to file management features. These scopes allow users to upload new files to the platform as well as download them from Alphamoon to users device.

<table><thead><tr><th width="360">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.file:upload"</td><td>Grants access to upload files to Alphamoon.</td></tr><tr><td>"workspace.file:download"</td><td>Grants access to download uploaded files to the user's device.</td></tr></tbody></table>

### Results

Results API scopes enable access to the processed extraction results of uploaded documents. Users can retrieve, review, update, and delete the results, as well as create new ones when necessary.

<table><thead><tr><th width="372">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.result:read" </td><td>Grants access to read the extraction result.</td></tr><tr><td>"workspace.result:update"</td><td>Grants access to edit the extraction result (e.g. adding or deleting extractions). </td></tr></tbody></table>

### Processes

Processes API scopes encompass the coordination and oversight of document processing workflows, enabling users to view, update, and delete processes, as well as manage them.

<table><thead><tr><th width="372">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.process:read" </td><td>Grants access to view all processes (e.g. enter the <a href="../platform-walkthrough/queue">Queue</a>, <a href="../platform-walkthrough/supervision">Supervision</a>).</td></tr><tr><td>"workspace.process:update" </td><td>Grants access to edit processes and their configuration.</td></tr><tr><td>"workspace.process:delete" </td><td>Grants access to delete processes.</td></tr><tr><td>"workspace.process.api_key:manage"</td><td>Grants access to create process API keys.</td></tr></tbody></table>

### Destinations

Destinations API scopes enable the configuration and management of data destinations. Users can specify where results are sent, ensuring they reach the appropriate systems or storage locations.

<table><thead><tr><th width="371">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.destination:create" </td><td>Grants access to configure data destinations.</td></tr><tr><td>"workspace.destination:read" </td><td>Grants access to view the data destinations.</td></tr><tr><td>"workspace.destination:delete"</td><td>Grants access to delete the data destinations.</td></tr></tbody></table>

### Exports

Exports API scopes provide functionality for exporting processed data, including options for defining export formats, and deleting existing exports if necessary.

<table><thead><tr><th width="365">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.export:create"  </td><td>Grants access to create new exports.</td></tr><tr><td>"workspace.export:delete"</td><td>Grants access to delete created exports.</td></tr></tbody></table>

### Users administration

Users Administration API scopes allow Admins to create, modify, and control user access to ensure secure and efficient work with Alphamoon.

<table><thead><tr><th width="337">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.admin.user:read" </td><td>Grants access to view user's details.</td></tr><tr><td>"workspace.admin.user:invite" </td><td>Grants access to inviting new users to Alphamoon.</td></tr><tr><td>"workspace.admin.user:manage"</td><td>Grants access to manage Alphamoon users.</td></tr></tbody></table>

### Process administration

Process Administration API scope enables managing and configuring document processing workflows.

<table><thead><tr><th width="337">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.admin.process:manage"</td><td>Grants access to manage (create, update, and delete) all processes in Alphamoon.</td></tr></tbody></table>

### API key administration

API Key Administration scope allows administrators to manage all API keys, essential for secure access to Alphamoon's features, and maintain control over application integrations and data access. Administrators can create and delete API keys.

<table><thead><tr><th width="337">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.admin.api_key:manage"</td><td>Grants access to manage all API keys in the organization.</td></tr></tbody></table>

### Subscription administration

The following scope enable administrators to manage and modify organization subscription.

<table><thead><tr><th width="362">Scope</th><th>Description</th></tr></thead><tbody><tr><td>"workspace.admin.subscriptions:manage"</td><td>Grants access to manage the organization's subscription plan.</td></tr></tbody></table>

**See next:**