HomeEngagementOther resources
API reference

Authorization errors

Authorization errors occur when the Tracking API can't verify your credentials. They can also occur when your API key lacks permission to perform the requested action. These errors return immediately with 4xx status codes, preventing the request from processing.

How to resolve authorization errors

  • Verify your project token is correct and complete.
  • Ensure your API key appears in request headers.
  • Confirm your API key has the necessary permissions for the operations you're attempting.

Error types

400 - Could not authenticate / Invalid project ID

This error occurs when your project token is incorrect, malformed, or missing characters.

Example:

Request with incomplete project ID:

curl --location 'https://api-cis.exponea.com/track/v2/projects/c178a8c8-5cea-11e8-aa8c-ac1f6b0/batch' -i \
--header 'content-type: application/json' \
--header 'Authorization: *************' \
--data-raw '{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "registered": "[email protected]"
        },
        "event_type": "cart_update",
        "properties": {
          "product_id": "X1"
        }
      }
    }
  ]
}'

Response to the request:

HTTP/2 400
content-type: application/json
x-request-id: f84f7f6c-02c0-4ff8-a9df-872d8103e5d5
date: Wed, 31 Jul 2024 21:30:39 GMT

{"success":false,"error":"Could not authenticate"}

// or {"success":false,"error":"Invalid project id"}

In this example, the project ID c178a8c8-5cea-11e8-aa8c-ac1f6b0 is missing several characters at the end, causing authentication to fail.

JSON response example:

{
"success":false,
"error":"Invalid project id"
}

or

{
"success":false,
"error":"Could not authenticate"
}

Resolution:

Verify your project token is complete and matches the token provided in your Bloomreach Engagement project settings.

401 - Access key not provided

This error occurs when the authorization header is missing or formatted incorrectly.

Example:

Request without authorization header:

curl --location 'https://api-cis.exponea.com/track/v2/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/batch' -i \
--header 'content-type: application/json' \
--data-raw '{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "registered": "[email protected]"
        },
        "event_type": "cart_update",
        "properties": {
          "product_id": "X1"
        }
      }
    }
  ]
}'

Response to the request:

HTTP/2 401
content-type: application/json
x-request-id: 1b50052d-3488-4e32-8081-a77954937945
date: Wed, 31 Jul 2024 21:28:12 GMT

{"success":false,"error":"access key not provided"}

JSON response example:

{
"success":false,
"error":"access key not provided"
}

Resolution:

Add the authorization header to your request with your API key:

--header 'Authorization: Basic *************'

403 - No permission

This error occurs when your API key is valid but doesn't have permission to perform the requested action. The error message specifies what permission is missing.

Example scenario 1: Unauthorized event tracking

Request attempting to track a restricted event type:

curl -i --location 'https://api-cis.exponea.com/track/v2/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/customers/events' \
--header 'content-type: application/json' \
--header 'Authorization: Basic *************' \
--header 'X-Forwarded-For: 91.64.216.106' \
--data-raw '{
  "customer_ids": {
    "registered": "[email protected]"
  },
  "properties": {
    "action_type": "whatsapp",
    "status": "delivered",
    "recipient": "123456"
  },
  "event_type": "campaign"
}'

Response to the request:

HTTP/2 403
content-type: application/json
x-request-id: 856742ea-30b8-4d5e-a522-3ddfae916390
date: Tue, 28 Oct 2025 13:13:35 GMT

{"success":false,"errors":["not authorized to add event of specified type"]}

JSON response example:

{
"success":false,
"errors":
["not authorized to add event of specified type"]
}

Example scenario 2: Unauthorized customer property update

Request attempting to update restricted customer properties:

curl -i --location 'https://api-cis.exponea.com/track/v2/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/customers' \
--header 'content-type: application/json' \
--header 'Authorization: Basic *************' \
--data-raw '{
  "customer_ids": {
    "registered": "[email protected]"
  },
  "properties": {
    "email": "[email protected]",
    "first_name": "Nikolay",
    "phone": "123456"
  },
  "update_timestamp": 1758099531.33333336
}'

Response to the request:

HTTP/2 403
content-type: application/json
x-request-id: b5368b69-4e14-43e0-8068-0e44857f81ba
date: Tue, 28 Oct 2025 13:16:05 GMT

{"success":false,"errors":["not authorized to update specified customer properties"]}

JSON response example:

{
"success":false,
"errors":
["not authorized to update specified customer properties"]
}

The system aborts the entire customer update even when the API key has permission to update some properties. In this example, the API key can update phone and first_name, but the restricted email property causes the entire update to fail.

Example scenario 3: Permission errors in batch requests

Batch requests return status 200 at the top level, with individual command errors shown in the results array.

Request with multiple commands, some lacking permissions:

curl --location 'https://api-cis.exponea.com/track/v2/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/batch' -i \
--header 'content-type: application/json' \
--header 'Authorization: *************' \
--data-raw '{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "registered": "[email protected]"
        },
        "event_type": "cart_update",
        "properties": {
          "product_id": "X1"
        }
      }
    },
    {
      "name": "customers",
      "data": {
        "customer_ids": {
          "registered": "[email protected]"
        },
        "properties": {
          "email": ""
        }
      }
    }
  ]
}'

Response to the request:

HTTP/2 200
content-type: application/json
x-request-id: c3520ff1-2565-464e-bfef-21b3f8470572
date: Tue, 28 Oct 2025 13:08:52 GMT

{
  "results": [
    {
      "success": false,
      "errors": ["not authorized to add event of specified type"]
    },
    {
      "success": false,
      "errors": ["not authorized to update specified customer properties"]
    }
  ],
  "start_time": 1761656932.260703,
  "end_time": 1761656932.2609189,
  "success": true
}

JSON response example:

{
  "results": [
    {
      "success": false,
      "errors": ["not authorized to add event of specified type"]
    },
    {
      "success": false,
      "errors": ["not authorized to update specified customer properties"]
    }
  ],
  "start_time": 1761656932.260703,
  "end_time": 1761656932.2609189,
  "success": true
}

Resolution:

Update your API key permissions in Bloomreach Engagement to include the event types and customer properties you're trying to track or update. Contact your project administrator if you don't have permission to modify API key settings.

Related resources