Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt

Use this file to discover all available pages before exploring further.

API keys provide a simple way to authenticate programmatic requests against the NeuronSearchLab Platform API. Unlike SDK Credentials, which issue OAuth access tokens for the Core API, API keys are Bearer tokens for server-side console automation.

​
When to use API keys vs SDK credentials

API KeysSDK Credentials
Auth methodBearer token (nsl_...)OAuth 2.0 client credentials
EndpointPlatform APICore API
Rerank controlsRead and update configurationUsed only when serving code calls the Core API
Use caseInternal tools and console automationProduction recommendation, event, and catalog integration

​
Create an API key

1

Open API Keys

Navigate to Console > API Keys.
2

Start a new key

Click New API Key.
3

Name the key

Enter a descriptive name, for example “Staging Backend” or “Internal Dashboard”.
4

Tag the environment

Select an environment tag for organisational purposes.
5

Choose scopes

Choose which scopes the key can access: recommendations, events, or items.
6

Create the key

Click Create Key.
The full key is displayed once. Copy it immediately and store it securely.

​
Authenticate requests

Include your API key as a Bearer token in the Authorization header: 
curl "https://console.neuronsearchlab.com/api/rerank-controls?contextId=101" \
  -H "Authorization: Bearer nsl_abc12345_..."
For recommendation serving, use SDK Credentials with the Core API instead of API keys.

​
Key format

API keys follow the format nsl_<prefix>_<token>:
  • nsl_ — fixed prefix identifying a NeuronSearchLab key.
  • <prefix> — 8-character identifier shown in the console for easy recognition.
  • <token> — the full random token. Only the SHA-256 hash is stored server-side.

​
Scopes

Each key is restricted to specific API scopes:
ScopeGrants access to
recommendationsReserved for recommendation-related internal tools. Current documented Platform API routes use admin unless stated otherwise.
eventsEvent configuration routes that explicitly allow the events scope.
itemsReserved for catalog automation routes that explicitly allow the items scope.
adminFull Platform API access.
If a key lacks the required scope, the Platform API returns 403 Forbidden.

​
Revoke a key

1

Open API Keys

Navigate to Console > API Keys.
2

Revoke the key

Click Revoke on the key you want to deactivate.
Revocation is immediate and permanent. Create a new key if you need to restore access.

​
Security practices

  • One key per service or environment. Avoid sharing keys across applications.
  • Tag keys with the correct environment to make auditing easier.
  • Rotate keys periodically. Create a new key, deploy it, then revoke the old one.
  • Never expose keys client-side. API keys are for server-to-server use only.