Access Control List

Access Control List (ACL) allows you to set specific permissions for users and API keys. This feature is particularly useful for restricting access to certain resources or actions within your project.

Available Permissions

The following permissions are available for custom access control list. Each custom permission includes a read permission for indices by default, as it is generally required to manage most resources. Additionally, every modify access level implicitly includes read access.

A/B Tests

  • ab_tests.read: Grants access to view A/B test configurations.
  • ab_tests.modify: Grants access to manage A/B test configurations.

Analytics

  • analytics.read: Grants access to view analytics.

API Keys

  • api_keys.read: Grants access to view API keys.
  • api_keys.modify: Grants access to manage API keys.

Documents

  • documents.read: Grants access to view documents.
  • documents.modify: Grants access to manage documents, including importing documents/products to your indices.

Import Templates

  • import_templates.read: Grants access to view import templates.
  • import_templates.modify: Grants access to manage import templates.

Keywords

  • keywords.read: Grants access to view keywords.
  • keywords.modify: Grants access to manage keywords.

Recommendation Queries

  • recommendation_queries.read: Grants access to view recommendation queries, including recommendation rule configurations.
  • recommendation_queries.modify: Grants access to manage recommendation queries, including managing recommendation rule configurations.

Redirections

  • redirections.read: Grants access to view redirection rules.
  • redirections.modify: Grants access to manage redirection rules.

Indices

  • indices.modify: Grants access to manage indices, including creating, updating, and deleting indices, as well as performing re-index operations and index mapping modifications.

Search Queries

  • search_queries.read: Grants access to view search queries, including configured search query rules and errors.
  • search_queries.modify: Grants access to manage search queries, including managing search query rules and custom ranking.

Suggestions

  • suggestions.read: Grants access to view custom suggestions.
  • suggestions.modify: Grants access to manage search suggestions, including adding custom suggestions and initiating suggestion generation.

Synonyms

  • synonyms.read: Grants access to view synonyms.
  • synonyms.modify: Grants access to manage synonyms.

Tasks

  • tasks.read: Grants access to view tasks, including import, re-index, suggestion generation tasks, and monitoring of potential errors.

Setting Custom Access for a User

To set custom access for a user, send an HTTP PUT request to the user update endpoint using an existing userId:

PUT /organizations/{organizationSlug}/projects/{projectSlug}/users/{userId}

Include PROJECT_CUSTOM role and a list of permissions you want to grant to the user in the request body:

{
  "role": "CUSTOM",
  "permissions": ["tasks.read", "documents.modify"]
}

Setting custom access for API Key

To set custom access for an API key, send an HTTP PUT request to update an existing API key, or use an HTTP POST request to create a new API key with custom permissions:

PUT /organizations/{organizationSlug}/projects/{projectSlug}/apiKeys/{apiKeyId}

or

POST /organizations/{organizationSlug}/projects/{projectSlug}/apiKeys

{
  "description": "Api Key to read analytics data",
  "access": "custom",
  "permissions": ["analytics.read"]
}

You can further restrict API key access by limiting access to specific indices only. To do this, set restrictIndexScope to true and provide a list of indexIds in the request body.

{
  "description": "Api Key to import documents to once specific index only",
  "access": "custom",
  "permissions": ["documents.modify"],
  "restrictIndexScope": true,
  "indexIds": ["107d0bdc-4187-4447-a0a9-5c046df76dec"]
}

Viewing Custom Access

/v1/users/me endpoint will include the current permissions of the requesting user/api key in response:

{
  "id": "ad8eb8b7-bef6-45c0-8162-901c4d724ea2",
  "email": "[email protected]",
  "organizations": [
    {
      "id": "dbcde45b-2201-46c4-8f32-7f8f425ee76f",
      "name": "Lupasearch",
      "slug": "lupasearch",
      "role": "ORGANIZATION_MEMBER",
      "projects": [
        {
          "id": "c5f44ecd-357a-48ed-b510-516b9a99d6b4",
          "name": "Lupasearch Store",
          "slug": "lupasearch-store",
          "role": "PROJECT_CUSTOM",
          "permissions": [
            "ab_tests.read",
            "analytics.read",
            "keywords.read",
            "redirections.read",
            "search_queries.read",
            "synonyms.read"
          ]
        }
      ]
    }
  ],
  "featureQuotas": {}
}

Additionally, permission data will be included with returned users to the accounts that have access to the user management endpoints.