API Authentication

This section of the documentation covers the authentication process using JWT access tokens and API keys. JWT access tokens are used to authenticate individual user actions, while API keys are used for server-to-server interactions.

JWT Access Token

Obtaining Jwt Access Token

If you use API to configure Indices or Queries, or to upload Documents, you need to obtain Jwt Access token first.

Request

To do that, issue an HTTP POST request to the login endpoint:

/v1/users/login

With your email and password in the request body:

{
  "email": "[email protected]",
  "password": "my_secure_password"
}

Response

If your credentials are correct, you will receive the Jwt access token in the following format:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ..."
}

Access Token will expire in 1 hour. After that, a new token must be obtained.

Using Access Token

Obtained Access token needs to be attached to the Authorization header of every API request that requires authentication.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...

Testing Access Token

To check whether access token is working and is attached correctly, you can issue an HTTP GET request to the users/me endpoint.

/v1/users/me

If everything works correctly, you will receive information about the current user:

{
  "id": "de4e47ca-d76e-4d8a-a7f2-dea5f3787059",
  "email": "[email protected]",
  "createdAt": "2021-10-15T13:23:36.000Z",
  "updatedAt": "2021-10-15T13:23:36.000Z",
  "organizations": [
    {
      "id": "a0721954-1964-41d1-9135-8459f0b06b2c",
      "name": "Your Organization",
      "slug": "your-organization",
      "createdAt": "2021-10-28T12:32:19.000Z",
      "updatedAt": "2021-10-28T12:32:19.000Z",
      "role": "ORGANIZATION_ADMIN"
    }
  ]
}

API Keys

Obtaining API Key

To create an API Key for the project, send an HTTP POST request to the API key generation endpoint:

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

Request

Your request body must include the following parameters:

• description: Provide a brief explanation of where and how the API key will be used. This helps in identifying the purpose of the key, especially when multiple keys are in use.
• access: Set the access level for the API key. Choose between read, full and custom. Use read for retrieval-only operations and full for both retrieval and managing operations. To read more about the custom access level, see Custom Access Control Levels.
• restrictIndexScope: Restrict API key access to specific indices only. Set false to allow access to the all project's indices. Set true to restrict access only to indices specified in the indexIds parameter.
• indexIds: This is a list of IDs of search indices. It takes effect only if restrictIndexScope is set to true. Provide the IDs of the specific indices you want the API key to access.
• expiration: Set the validity for the API key. Provide a value in timestamp format for a specific expiration date, or set to null for no expiration.

Request example:

{
  "description": "This API key used in staging environment for products import",
  "access": "full",
  "restrictIndexScope": true,
  "expiration": null,
  "indexIds": ["107d0bdc-4187-4447-a0a9-5c046df76dec"]
}

Response

{
  "id": "b2381908-eb9c-47b5-9e3b-a6986e000939",
  "visibleKey": "SOF*****cl7",
  "description": "This API key used in staging environment for products import",
  "access": "full",
  "restrictIndexScope": true,
  "indexIds": ["107d0bdc-4187-4447-a0a9-5c046df76dec"],
  "expiration": null,
  ...
  "key": "SOFKt8Xg6b98L30euM0K4vVR34U8y5hoiagUDBlxsRhmSgNcl7"
}

The key value in the response refers to the API Key which can be used for subsequent requests with X-Lupa-API-Key request header.

Using API Key

To use the API key, include it in the X-Lupa-API-Key header of your API requests:

X-Lupa-Api-Key: SOFKt8Xg6b98L30euM0K4vVR34U8y5hoiagUDBlxsRhmSgNcl7

Note: Ensure that you keep your API keys secure and do not expose them in client-side code. If you believe an API key has been compromised, it is critical to revoke and replace it immediately. Additionally, it's important to note that Public Query requests do not require any API key or token and can be safely called from the client-side without it.