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.

# .env: one key for every pool
LASSO_RPC_URL=https://lasso.sh/rpc/k/lasso_…

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

<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.
<strategy> is optional; load-balanced is the default. See 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:

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.

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.

Rotate with no downtime

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

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

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.

Custom profiles: put your own providers behind a profile slug.
Serving access and pricing: what each profile costs.
Install Lasso in your app: client examples.

Start here

Concepts

Guides

Reference

Keys, URLs and profiles

Keys, URLs and profiles

URL grammar

Default and allowed profiles

Scope a key

How a profile segment resolves

Rotate with no downtime

Existing URLs keep working

Limits

Next

​Keys, URLs and profiles

​URL grammar

​Default and allowed profiles

​Scope a key

​How a profile segment resolves

​Rotate with no downtime

​Existing URLs keep working

​Limits

​Next

Keys, URLs and profiles

URL grammar

Default and allowed profiles

Scope a key

How a profile segment resolves

Rotate with no downtime

Existing URLs keep working

Limits

Next