# Authentication

> Source: `src/content/docs/actors/authentication.mdx`
> Canonical URL: https://rivet.dev/docs/actors/authentication
> Description: Secure your actors with authentication and authorization.

---
## Do You Need Authentication?

### Rivet Cloud

	Actors are private by default on Rivet Cloud. Only requests with the publishable token can interact with actors.

	- **Backend-only actors**: If your publishable token is only included in your backend, then authentication is not necessary.
	- **Frontend-accessible actors**: If your publishable token is included in your frontend, then implementing authentication is recommended.

### Self-Hosted

	Actors are public by default on self-hosted Rivet. Anyone can access them without a token.

	- **Only accessible within private network**: If Rivet is only accessible within your private network, then authentication is not necessary.
	- **Rivet exposed to the public internet**: If Rivet is configured to accept traffic from the public internet, then implementing authentication is recommended.

## Authentication Connections

Authentication is configured through either:

- `onBeforeConnect` for simple pass/fail validation
- `createConnState` when you need to access user data in your actions via `c.conn.state`

## Access Control

After a connection is authenticated, use [Access Control](/docs/actors/access-control) to enforce authorization:

- Check permissions in action handlers.
- Use `queues.<name>.canPublish` to gate inbound queue publishes.
- Use `events.<name>.canSubscribe` to gate event subscriptions.

### `onBeforeConnect`

The `onBeforeConnect` hook validates credentials before allowing a connection. Throw an error to reject the connection.

### `createConnState`

Use `createConnState` to extract user data from credentials and store it in connection state. This data is accessible in actions via `c.conn.state`. Like `onBeforeConnect`, throwing an error will reject the connection. See [connections](/docs/actors/connections) for more details.

## Available Auth Data

Authentication hooks have access to several properties:

| Property | Description |
|----------|-------------|
| `params` | Custom data passed by the client when connecting (see [connection params](/docs/actors/connections#extracting-data-from-connection-params)) |
| `c.request` | The underlying HTTP request object |
| `c.request.headers` | Request headers for tokens, API keys (does not work for `.connect()`) |
| `c.state` | Actor state for authorization decisions (see [state](/docs/actors/state)) |
| `c.key` | The actor's key (see [keys](/docs/actors/keys)) |

It's recommended to use `params` instead of `c.request.headers` whenever possible since it works for both HTTP & WebSocket connections.

## Client Usage

### Passing Credentials

Pass authentication data when connecting. Use `getParams` when you need a fresh JWT for every connection or reconnect:

### Handling Errors

Authentication errors use the same system as regular errors. See [errors](/docs/actors/errors) for more details.

## Examples

### JWT

Validate JSON Web Tokens and extract user claims:

### External Auth Provider

Validate credentials against an external authentication service:

### Using `c.state` In Authorization

Access actor state via `c.state` and the actor's key via `c.key` to make authorization decisions:

### Role-Based Access Control

Create helper functions for common authorization patterns:

### Rate Limiting

Use `c.vars` to track connection attempts and rate limit by user:

The limits in this example are [ephemeral](/docs/actors/state#ephemeral-variables). If you wish to persist rate limits, you can optionally replace `vars` with `state`.

### Caching Tokens

Cache validated tokens in `c.vars` to avoid redundant validation on repeated connections. See [ephemeral variables](/docs/actors/state#ephemeral-variables) for more details.

## API Reference

- [`AuthIntent`](/typedoc/types/rivetkit.mod.AuthIntent.html) - Authentication intent type
- [`OnBeforeConnectContext`](/typedoc/interfaces/rivetkit.mod.OnBeforeConnectContext.html) - Context for auth checks
- [`OnConnectContext`](/typedoc/interfaces/rivetkit.mod.OnConnectContext.html) - Context after connection

_Source doc path: /docs/actors/authentication_