> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens

Tokens can be used to:

* restrict access to private Channels
* forcefully subscribe users to Channels
* authenticate and identify users connected to Channels
* send direct messages to users (instead of to entire Channels)

Tokens can be generated using our API, then you can pass them down to users so
they can authenticate with Channels. A common implementation is to generate a
Token per user on your backend, then store it with the user object in your
database. You can then pass their token down to the user (via your API, for
example) and it can be used with our
[Client-side SDK](./tokens#using-tokens-with-client-side-sdks) to
authenticate with Channels.

## Do I need to use Tokens?

Tokens are **not necessary** in every application. Some applications may choose
to use Tokens for logged in users only, or even not at all - it really depends
on your use case.

If you're providing data that you want everyone to be able to see (without
signing into your app, for example) then it probably makes the most sense to use
an `unprotected` channel, which can be subscribed to using our frontend SDKs
without using Tokens.

A good use-case for Tokens would be if you're building something like a group
messaging app, for example, and need to limit access to certain channels, such
as private group chat channels, to specific users.

## Server-side Examples

<Note>
  The examples below assume you have already set up the [Hop server-side
  SDK](/sdks/server/js).
</Note>

### Generating Tokens

You can generate Tokens manually (using our Console) or via our SDKs & API.

Here's an example of generating tokens using the server-side SDK:

```js create-token.js theme={null}
// Import your Hop SDK instance
import {hop} from '.';
const {id} = await hop.channels.tokens.create(); // id = leap_token_xxx - you can now store and pass this token to clients
```

### Subscribing Tokens to Channels

When you subscribe a Token to a channel, it will be subscribed to that channel
in realtime and it will be made available to any live connections using that
Token.

In this example, let's assume that we have a private channel with the ID `game`.

```js subscribe-token.js theme={null}
// Import your Hop SDK instance
import {hop} from '.';

const channelId = 'game';
const userToken = 'leap_token_abc123';

await hop.channels.subscribeToken(channelId, userToken);
```

### Sending Messages Directly to Tokens

```js send-message-to-token.js theme={null}
// Import your Hop SDK instance
import {hop} from '.';

const userToken = 'leap_token_abc123';
const eventName = 'NOTIFICATION'; // this can be anything you want

await hop.channels.publishDirectMessage(userToken, eventName, {
	title: 'Someone liked your post!',
	description: 'Tap to view more.',
});
```

### Determine if a Token is Online

You can use the `isOnline` function to check if a Token is currently connected
to Channels.

```js is-token-online.js theme={null}
// Import your Hop SDK instance
import {hop} from '.';
const userToken = 'leap_token_abc123';

const isOnline = await hop.channels.tokens.isOnline(userToken);
// isOnline: boolean
```

## Client-side Examples

### Using Tokens with Client-side SDKs

Implementing Tokens into your frontend app is super easy. Just pass it into
`hop.init` in the `token` key. For example:

```js index.js theme={null}
import { hop } from "@onehop/client";

// hop.init should be called as early as possible in your application's lifecycle
// or, as soon as you have the leap token available
const client = hop.init({
	projectId: "project_xxx": // replace with your project ID,
	token: "leap_token_xxx" // the Token to authenticate with
});

// Optionally do something with the client
client.on('STATE_UPDATE', console.log);
```