---
title: HTTP API - Authorization
slug: cloud/http-api/authorization
docTags: 
createdAt: 2023-10-13T20:02:38.632Z
---

Access to the Ditto HTTP API is controlled through an `Authorization: Bearer HTTP` header. To authenticate and gain access to the Big Peer, use a static API key.

# API Key

Accessible from the portal, the API key is a straightforward implementation for authenticating your data product's digital identity with the Big Peer for authorization. 

The API key is a broad, long-lived HTTP API key that, once generated, remains valid for a maximum of one year. [​](https://legacydocs.ditto.live/http/installation#api-key)

## Security Overview

Ditto implements strong security practices for generating and handling API keys. 

- The API key is made up of a combination of random and fixed elements:
  - Randomly-generated prefix
  - Fixed prefix
  - Randomly-generated suffix
- Once received, the Big Peer performs a hashing process on the suffix element before securely storing the API key.

## Creating and Saving API Keys

To generate and retrieve the API key you'll include in your request header, from the portal, do the following:

:::hint{type="info"}
You need elevated access permissions to create and save API keys. You can perform this action only if your assigned role has the **Access API keys** setting enabled in the portal under **Settings** > **Roles**. (See [Role-Based Access Control](docId\:TFEyUSG0hUGhfBFxvie81))
:::

:::::WorkflowBlock
:::WorkflowBlockItem
Log in to the [portal](https://portal.ditto.live/) > click **Apps** > and then select your app from the list. 
:::

:::WorkflowBlockItem
Click **Auth**, and then click **New API key **from the lower right corner.

![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/7sA9d9zS9GnGL_731Ox0d_createapikey.png)
:::

::::WorkflowBlockItem
Complete the **Key configuration** form:

1. For **API Key Description**, enter a description of the key's intended use.
2. For **API Key Expiration**, if you want to adjust the default date that appears, click the date and then select the date you want from the calendar picker. 
3. For **Read Permissions**, select the option you want to set for read permissions. 
4. For **Write Permissions**, select the option you want to set for write permissions. 

:::hint{type="info"}
For more information about custom access rules, see [Setting Up Custom Permissions](./#setting-up-custom-permissions), as follows.
:::
::::

:::WorkflowBlockItem
Click **Create API Key**.

![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/v9g8l2RfE5F7XJ25VH-h2_create-api-keyform.png)
:::

:::WorkflowBlockItem
From the **API key created **dialog box:

1. Copy your API key and save it in a safe location.
2. Once saved, click **I have saved my API key**, and then click **Done**.

::Image[]{src="https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/RrawjSomij16ZIZ3koDvK_createapikeycopy.png" size="70" width="1339" height="770" position="flex-start" showCaption="false"}
:::
:::::

### Setting Up Custom Permissions

If you want to scope access to a particular collections or document IDs, set up custom access rules for **Read Permissions **or **Write Permissions**: 

:::::WorkflowBlock
:::WorkflowBlockItem
Select **Custom access rules** for the operation type you want to set up.
:::

:::WorkflowBlockItem
To scope by collection, enter the **Collection Name**.
:::

::::WorkflowBlockItem
To scope by a specific document, from **Queries**, enter your query expression.

:::hint{type="info"}
Currently, you can only set permission queries on the `_id` field; however, Ditto is actively developing a solution for setting queries by mutable fields.
:::

:::hint{type="info"}
If invoking the `FindByID` method, instead of using `_id`, pass the document ID as `id`.
:::
::::

:::WorkflowBlockItem
To add an additional rule, click **Add query rule** and then repeat step 2 and 3.

![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/LGgd5ljD7LuOzLH9_k-jw_create-api-keycustom.png)
:::
:::::

## Including the API Key

Once you've retrieved your API key, you can make requests to the Big Peer by including your key in the `Authorization: Bearer` HTTP header of each of your requests, as demonstrated in the following `POST` request:

:::CodeblockTabs
cURL

```curl
curl --location --request POST 'https://{YOUR_APP_ID}.cloud.ditto.live/api/v4/store/write' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "commands": [{
      "method": "upsert",
      "collection": "people",
      "value": {
        "name": "Susan", "age": 31
      }
    }]
  }'
```
:::

# Errors

Most HTTP API errors are indicated with an HTTP Status Code and a JSON response body containing an object with a single "error" key. 

:::hint{type="info"}
In some cases such as a Bad Gateway or Request Timeout only a plain text error or `{"message": "Request Timeout"}` JSON object is returned.
:::

If you receive a JSON response containing an `error` field name, its associated field value may be any of the following:

| **Value**       | **Description**                                                        |
| --------------- | ---------------------------------------------------------------------- |
| `error.code`    | The HTTP Status Code for                                               |
| `error.message` | A short description of the error                                       |
| `error.data`    | An optional object which contains further elaboration about the error. |

# Transactions

Each write request — either a `POST` or `DELETE` request — to the HTTP API represents a distinct transaction; and each transaction may consist of a single operation or multiple operations.

If a request to insert an event successfully executes on the Big Peer, the server includes a transaction ID in its response. You can then include that ID in subsequent `GET` requests to ensure you're accessing only the most up-to-date and accurate information for that particular event. For more information, see [Transaction IDs](./#transaction-ids), as follows.

## Transaction IDs

When retrieving events associated with a specific transaction, ensure data consistency by referencing its unique ID in your `GET` request. By including the transaction ID, you ensure that you're working with the most up-to-date and accurate information by instructing Ditto to wait until the events related to that transaction have been fully processed and replicated across the entire mesh before being fetched. 

:::hint{type="info"}
If you do *not* supply the transaction ID in your request, Ditto defaults to using the most recent version of the transaction that is common to all Ditto nodes. 
:::

:::hint{type="info"}
Transaction IDs instruct the Big Peer on the order in which transactions should be applied. For more information, see the *Platform Manual *> [Big Peer](docId:2felXG8G6acWURCgp-hHk).
:::

### Specifying Transactions by ID

When making a `GET` request to `find` a specific event, instruct Ditto to wait until the associated transaction has been fully applied across the entire mesh network before accessing it. This ensures that you're working with the most up-to-date and accurate information.

To specify a transaction by its associated ID, in your `GET` request to the `find` URL endpoint, include the optional `X-DITTO-TXN-ID` header set to the value of the transaction ID. For example, a returned transaction ID of `14`:

:::hint{type="warning"}
If the version of the data being requested is not yet available on the server, an error will be included in the response.
:::

:::CodeblockTabs
cURL

```curl
curl -X GET 'https://{app_id}.cloud.ditto.live/api/v4/store/find' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'X-DITTO-TXN-ID: 17'
```
:::