> ## 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.

# Authentication

> Which credential to use where, and how to turn SDK credentials into an access token.

NeuronSearchLab has three kinds of credential. Pick the one that matches where your code runs.

| Credential | Looks like | Use it for | Where it may live |
| - | - | - | - |
| **SDK credentials** | Client ID and client secret | Your application calling the [Core API](https://docs.neuronsearchlab.com/api-reference/introduction.md): items, events, recommendations, search | Your servers only |
| **API key** | `nsl_<prefix>_<token>` | Automation, internal tools and AI assistants calling the [Platform API](https://docs.neuronsearchlab.com/api-reference/platform-api/introduction.md) | Your servers or an assistant's secure config |
| **Publishable key** | `nsl_pk_…` | The [Website embed](https://docs.neuronsearchlab.com/embed.md) in a visitor's browser | Public web pages, restricted to origins you list |

> [!WARNING]
>
> Never put a client secret, an access token or an `nsl_` API key in browser or mobile code. Anyone who can read your page source or app bundle could use it. The publishable key is the only credential designed to be public.

Mobile apps should call your own backend, which holds the credentials and calls NSL. The [Swift SDK](https://docs.neuronsearchlab.com/sdk/swift.md) accepts a static token for trusted runtimes; it does not make a workspace-wide token safe to distribute in a mobile app.

## SDK credentials

Create them in **Developers → SDK Credentials**. See [SDK Credentials](https://docs.neuronsearchlab.com/console/sdk-credentials.md) for the console steps. Create one credential per application and environment, so you can revoke one without affecting the others.

### Let the SDK manage tokens

The JavaScript and PHP SDKs exchange the credentials for a token, cache it and refresh it before it expires:

```ts JavaScript theme={null}
import NeuronSDK from "@neuronsearchlab/sdk";

const sdk = new NeuronSDK({
  baseUrl: "https://api.neuronsearchlab.com/v1",
  oauthClientCredentials: {
    clientId: process.env.NSL_CLIENT_ID!,
    clientSecret: process.env.NSL_CLIENT_SECRET!,
  },
});
```

```php PHP theme={null}
use NeuronSearchLab\NeuronSDK;

$sdk = new NeuronSDK([
    'baseUrl' => 'https://api.neuronsearchlab.com/v1',
    'oauthClientCredentials' => [
        'clientId' => getenv('NSL_CLIENT_ID'),
        'clientSecret' => getenv('NSL_CLIENT_SECRET'),
    ],
]);
```

If a token is rejected with `401`, the SDK fetches a new one and retries the request once. If you already run your own token service, pass `tokenProvider` (a function that returns a token) or a static `accessToken` instead.

### Exchange credentials yourself

Without an SDK, call the token endpoint with HTTP Basic authentication:

```bash theme={null}
curl -X POST https://auth.neuronsearchlab.com/oauth2/token \
  -H "Authorization: Basic <base64(client_id:client_secret)>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

```json theme={null}
{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "neuronsearchlab-api/read neuronsearchlab-api/write"
}
```

Then send the token on every Core API call:

```http theme={null}
Authorization: Bearer eyJ...
```

Use the returned `expires_in` value to determine token lifetime. Cache one per credential, compute `expires_at = now + expires_in`, and fetch a new token a minute or so before it expires. Do not request a token per API call: the token endpoint is rate-limited separately.

### Scopes

| Scope | Allows |
| - | - |
| `neuronsearchlab-api/read` | Recommendations, search, and reading items and events |
| `neuronsearchlab-api/write` | Creating, updating and deleting items, and sending events |

A token carries both scopes unless you ask for fewer with the `scope` form field. Treat scope strings as opaque and split them only on spaces.

## API keys

Create them in **Developers → API Keys**, choosing which areas each key can reach. See [API keys](https://docs.neuronsearchlab.com/console/api-keys.md). Send a key as a bearer token:

```bash theme={null}
curl https://console.neuronsearchlab.com/api/rules \
  -H "Authorization: Bearer nsl_abc12345_..."
```

API keys are also how AI assistants connect through MCP. See [ChatGPT and MCP](https://docs.neuronsearchlab.com/sdk/mcp.md).

## Publishable keys

Created in **Developers → Website embed**, together with the list of origins allowed to use them. A publishable key can only fetch recommendations and report engagement with what it was shown. It cannot read your catalogue, change configuration or create other credentials. See [Website embed](https://docs.neuronsearchlab.com/console/website-embed.md).

## Good practice

* Use one credential per application and environment (production, staging).
* Rotate secrets by creating the new credential, deploying it, then revoking the old one.
* Revoke credentials as soon as a person or service no longer needs them. Revoking SDK credentials prevents new token issuance; already-issued access tokens may remain valid until expiry.
* Review **Account → Activity** to see when credentials were created, changed or revoked.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.