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

> ## Agent Instructions
> You are reading the Lanesurf Agent API docs. Start with /for-ai-agents.md for the rules an agent must follow.
> The API is at https://agent.lanesurf.com and the MCP server at https://agent.lanesurf.com/mcp. Lanesurf doesn't send webhooks: poll.
> Limits: /rate-limits.md. Keys: /api-keys.md. Safe retries: /idempotency.md. Every route on one page: /api-reference.md.
> Always confirm with the person before accepting a carrier offer or bidding on a load. Never reveal an API key, and never show broker contact details to a carrier.
> The full contract is at /openapi.yaml.
> Sign up with POST /v1/signup (carrier or broker, a work email, an MC and/or DOT number), then POST /v1/signup/{signup_id}/verify. Follow next_step on every signup answer.

# API keys

> How to get a Lanesurf API key, send it, keep it safe, replace it and revoke it.

A Lanesurf API key looks like `ls_live_…`. Send it as a bearer token on every request except signup and
`/health`:

```bash theme={null}
curl https://agent.lanesurf.com/v1/me -H "Authorization: Bearer ls_live_..."
```

## Get a key

| Who | How |
| - | - |
| Carrier or dispatcher | [Sign up](https://docs.lanesurf.com/carriers/sign-up.md): MC and/or DOT number, a work email and the 8-digit code Lanesurf emails. The key comes back from verify |
| New brokerage | [Sign up your brokerage](https://docs.lanesurf.com/brokers/get-a-key.md) the same way. Carrier outreach starts after Lanesurf's review |
| Brokerage that already uses Lanesurf | Your Lanesurf admin or account manager gives you a key. Or connect an AI app and sign in with your Lanesurf dashboard account: Lanesurf makes a broker key for you the first time |
| AI apps that can't send a header (ChatGPT, the Claude app) | Connect to `https://agent.lanesurf.com/mcp` by URL and sign in on the Lanesurf page (OAuth). See [Sign in from an AI app](https://docs.lanesurf.com/authentication.md#sign-in-from-an-ai-app) |

The key is shown **once**, in the verify answer. Lanesurf stores only a hash of it and can't show it again.

## What a key is

* One key = one rep at a brokerage (`role: broker`) or one carrier signup (`role: carrier`).
* Keys don't expire. A key works until it is revoked.
* `GET /v1/me` says who a key belongs to: `key_id`, `key_prefix` (the first characters, safe to show),
  `role`, and for carriers `verification`.
* A missing key answers `401 missing_api_key`; a wrong or revoked one answers `401 invalid_api_key`.

## OAuth tokens (AI apps)

When an app signs in on the Lanesurf page, it gets OAuth tokens instead of a raw key. Each sign-in stands
for one Agent API key.

| | |
| - | - |
| Flow | OAuth authorization code with PKCE and dynamic client registration (the MCP authorization spec) |
| Discovery | `https://agent.lanesurf.com/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource/mcp` |
| Scope | `lanesurf` (one scope: everything the key behind it can do). `offline_access` is accepted too; every sign-in gets a refresh token either way |
| Access token | Lasts 1 hour (`expires_in: 3600`) |
| Refresh token | Lasts 90 days. Each refresh returns a new access token and a new refresh token |
| Revocation | Revoking the key behind a sign-in signs the person out of every app; the next refresh answers `invalid_grant` |

## Replace (rotate) a key

To replace a key with a new one:

1. **Get a new key.** A carrier signs up again with the same MC/DOT number and work email (signup limits
   apply: 5 per email per hour). A broker asks their Lanesurf admin or account manager.
2. **Switch your agent** to the new key and check it with `GET /v1/me`.
3. **Revoke the old key:** email [support@lanesurf.com](mailto:support@lanesurf.com) with the old key's `key_prefix` (never the whole key).

## Revoke a key

If a key leaked, or a person left, email [support@lanesurf.com](mailto:support@lanesurf.com) with the `key_prefix` and say why.
Lanesurf revokes it; from then on it answers `401 invalid_api_key`, and every app signed in with it is
signed out.

## Keep keys secret

* Never paste a key into a chat, a ticket, a log or a URL. Show `key_prefix` instead.
* Store it as a secret (an environment variable such as `LANESURF_API_KEY`, or the connector's header field).
* An agent hands a new key to the person once, to store, and never repeats it.
* Use one key per person or per agent, so revoking one doesn't stop the others.


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