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

# Keys, URLs and profiles

> One key in .env reaches every profile of its account; the URL picks the profile, strategy and chain

# Keys, URLs and profiles

One RPC key, saved once in `.env`, reaches every profile its account has:
Lasso's `premium` and `public` pools and each of your Custom profiles. The URL
picks the profile, the strategy and the chain. Use this page to build URLs,
move an app between pools without a redeploy, scope keys you have to expose,
and rotate secrets with no downtime.

```bash theme={null}
# .env: one key for every pool
LASSO_RPC_URL=https://lasso.sh/rpc/k/lasso_…
```

```ts theme={null}
const url = process.env.LASSO_RPC_URL;
const reads  = `${url}/latency-weighted/base`;           // the key's default profile
const jobs   = `${url}/profile/public/base`;             // public providers, uncharged while the account has spending power
const trades = `${url}/profile/prod-base/fastest/base`;  // your own providers
```

## URL grammar

```text theme={null}
<base>[/profile/<profile>][/<strategy>]/<chain>
```

| Base | Form |
| - | - |
| `https://lasso.sh/rpc/k/<key>` | HTTP, key in the path (`rpc_url`) |
| `wss://lasso.sh/ws/rpc/k/<key>` | WebSocket, key in the path (`ws_url`) |
| `https://lasso.sh/rpc` | HTTP, key in `Authorization: Bearer <key>` or `x-lasso-api-key` |
| `wss://lasso.sh/ws/rpc` | WebSocket, key in `Authorization: Bearer <key>` or `x-lasso-api-key` |

* `<chain>` is a chain name or decimal chain ID from
  [chains and prices](/cloud/reference/chains-and-prices).
* `<strategy>` is optional; `load-balanced` is the default. See
  [routing](/cloud/routing).
* `<profile>` is `premium`, `public` or one of your Custom profile slugs.
  Without it, the key's default profile serves the request.
* `<base>[/profile/<profile>]/provider/<name>/<chain>` pins one provider for
  debugging. Managed providers use their public aliases.

Creating or rotating a key returns `rpc_url` and `ws_url` ready to use, with
nothing to fill in.

## Default and allowed profiles

| Field | What it does | Default |
| - | - | - |
| `default_profile` | The profile a URL with no profile segment uses | `premium` |
| `allowed_profiles` | The profiles the key can name in its URL | `all`: every current and future profile of the account |

Change a key's default, and every URL without a profile segment moves with it,
with no redeploy:

```http theme={null}
PATCH https://lasso.sh/api/v1/keys/{id}
Authorization: Bearer <management token>
Content-Type: application/json

{"default_profile": "prod-base"}
```

Making a Custom profile the default needs Custom access. Open WebSocket
connections that used the old default close with `default_profile_changed`,
and your client's reconnect follows the new default.

## Scope a key

`allowed_profiles` sets which profiles a key may use. A key scoped to a Custom
profile is served and charged as `premium` if Custom access lapses or the
profile is deleted.

```http theme={null}
POST https://lasso.sh/api/v1/keys
Authorization: Bearer <management token>
Content-Type: application/json

{"name": "jobs", "default_profile": "public", "allowed_profiles": ["public"]}
```

A scoped key that names another profile gets
`forbidden`, listing what it can use.

## How a profile segment resolves

| The URL names | Result |
| - | - |
| Nothing | The key's default profile |
| A profile the key is allowed | That profile |
| A profile outside a scoped key's allowed set | 403 `forbidden`, naming the allowed profiles |
| A slug the account has never had | 404 `unknown_profile`, listing the account's profiles |
| A Custom profile that was deleted, or whose Custom access lapsed | Served as `premium`, with `x-lasso-fallback: profile` |

Whether `premium` is served by premium providers depends on the account's
payment state, not the URL. See
[serving access and pricing](/cloud/serving-access-and-pricing).

## Rotate with no downtime

Rotate with an overlap, and both secrets work until `previous_valid_until`, so
your deploys can catch up:

```http theme={null}
POST https://lasso.sh/api/v1/keys/{id}/rotate
Authorization: Bearer <management token>
Content-Type: application/json

{"grace_seconds": 3600}
```

The response carries the new `key`, `rpc_url` and `ws_url`. Ship them, then
let the old secret expire. See
[rotate a key with no downtime](/cloud/guides/rotate-a-key) for the full
sequence.

## Existing URLs keep working

Every URL Lasso has issued keeps serving; the older forms and how they map are
on [upgrading from Agent API v2](/cloud/reference/v2-compatibility).

## Limits

* The API returns a key's secret only on create and rotate. If you lose it,
  rotate the key or create another; admins can view active keys' URLs in the
  dashboard.
* `grace_seconds` defaults to 0, which stops the old secret immediately; the
  maximum is 86,400.
* An account holds at most 100 active keys.
* `premium` and `public` are reserved; Custom profile slugs can't use them.

## Next

* [Custom profiles](/cloud/custom-profiles): put your own providers behind a
  profile slug.
* [Serving access and pricing](/cloud/serving-access-and-pricing): what each
  profile costs.
* [Install Lasso in your app](/cloud/install): client examples.


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