# Configure access

A project can have multiple named routing policies. Each API key belongs to one project and one policy. Several keys can share a policy—for example, when rotating credentials or connecting separate backend services with the same routing rules.

## Create your first integration

Choose your workspace and project in the app header. This context applies across dashboard pages; switching workspaces shows that workspace’s accessible projects.

1. Open **API keys** and choose **Mainnet** or **Testnet**.
2. Select **Create API key**. In the dialog, create a policy or select an existing policy for that network.
3. Review **Provider readiness**. For NEAR and SwapKit, choose **Use Route’s connection** or save your own provider credential. NEAR uses a partner API key; SwapKit uses an API key. Saving a credential selects your own account. Switching connections changes the provider version, so obtain fresh quotes for new payments. Existing NEAR preparations retain their connection source for tracking. The four public protocol adapters require no provider key. Garden is temporarily paused; saved credentials and settings are retained. See [provider connections](providers.md).
4. Select **Continue to key details**, then choose the key’s name, permissions and expiry. Advanced key restrictions are optional. Create the key and copy its secret once into your backend’s secret storage.
5. Use **Route simulator** to compare mainnet routes with the same named policy, then prepare the recommended payment. Testnet currently uses the [public API flow](testnet-api.md).

If you need to confirm a recent sign-in, request the verification email from the key form. Keep the form open, verify in another tab in the same browser, and return to create the key. Check spam or junk if the message is missing. Temporary delivery failures retry automatically. The link expires 15 minutes after it was requested; requesting another link invalidates the earlier one.

A policy does not fix an asset pair. Your application continues to supply source asset, destination asset and amount on each quote request. The API key selects its policy automatically; a quote request cannot override it with another policy ID.

## Check provider connections

Open **Provider health** to see saved connection results and their timestamps. For team members with provider-management access, opening this page checks enabled providers whose last check is missing or more than five minutes old. **Check all enabled** refreshes every enabled provider; **Check now** or **Retry check** refreshes one. Disabled providers are not checked. Other team members can view saved results.

These checks read public provider data; NEAR and SwapKit verify the selected connection with a dry quote. Paused providers are excluded from dashboard health checks. They do not move funds. **Check passed** confirms only that this check succeeded at the displayed time. It is not continuous uptime monitoring or approval for every route. Quotes and payment preparation still validate the requested assets, amount and execution requirements. **Check incomplete** means Route could not finish the check, such as a rate limit or a concurrent settings change; its message explains how to retry.

## Mainnet rules

Choose lowest estimated total cost or fastest estimated delivery. Set payment-value limits and a total fee budget in USD, optionally add an arrival deadline, and select the providers Route may consider. Route uses fresh asset prices; it does not assume every stablecoin is worth one dollar.

A route must satisfy the applicable policy checks before it can be recommended. Missing fees, prices or required arrival evidence remain unresolved. Provider readiness means the connection can be considered; exact assets, amount, liquidity and execution coverage are checked for each request.

The simulator highlights the best eligible route with enabled execution support, showing its estimated cost, recipient amount, delivery estimate and why it was chosen. **Prepare payment** opens the wallet and payment checks. It does not sign or move funds. Alternative quotes remain visible. If no route qualifies, the simulator explains the blockers; a lower observed cost is not presented as an approved route.

The API retains two selections: `selected` is the best eligible quote, and `executionSelection.candidateId` is the best eligible, unexpired quote with enabled execution support. These may differ. Neither substitutes for fresh wallet checks and exact customer signatures.

## Fastest estimates

Fastest compares estimated completion from **source funding broadcast, after wallet signing and token approvals**, to the recipient receipt with source and destination chain finality. It ranks the upper end of the estimated range, then cost for ties. An arrival deadline is checked against that same estimate; it is not a delivery guarantee.

For reviewed direct paths between Ethereum, Base, Arbitrum, Bitcoin, Tron, Solana and Stellar, `eta.basis: "modeled"` combines provider timing with explicit chain and processing allowances. NEAR uses a conservative source-finality allowance before its after-deposit estimate. SwapKit’s total already includes inbound, swap and outbound work; source finality overlaps that work instead of being added twice. Recent, healthy exact-path LayerZero history can be normalized the same way. Managed CCTP delivery to Stellar waits for both source finality and Circle attestation, then budgets up to two one-minute scheduling cycles and Stellar ledger close. CCTP Fast’s attestation time alone is not its completion estimate.

Bitcoin includes first inclusion and five further confirmations; Tron includes solidification, and Solana includes finalized commitment. Their ranges are engineering allowances around those confirmation rules, not statistical intervals or upper bounds on block production.

These are **low-confidence normal-operation budgets**, not measured percentiles or guaranteed bounds. In `view=full`, `eta.model` preserves the provider’s original duration and scope, the chain allowances, calculation assumptions and references. Both views retain the estimate's range, scope, basis and confidence. Non-CCTP provider work includes a disclosed 50% engineering margin. Approvals, time spent reviewing/signing, congestion, retries and service outages can add time. Overlapping ranges do not establish that one route will always finish first. Network finality checks during execution are unchanged.

Unreviewed networks, composed routes with intermediate authorizations, customer-submitted CCTP mints, missing durations, stale references and degraded history remain unranked until a complete model is available. The landing simulator uses recorded outputs from this same comparison engine, including the recording timestamp.

The chain allowances and Circle attestation timing are reviewed references that lapse 30 days after their review unless Route renews them; Route's operations monitor raises an alert seven days before either lapses. If the arrival model lapses, no route has end-to-end arrival evidence: speed priority and every delivery deadline leave all routes needing information, while lowest total cost without a deadline is unaffected. If only the Circle attestation timing lapses, managed CCTP delivery to Stellar loses its end-to-end estimate while the other modeled paths keep theirs. Policy reads and saves with speed priority or a deadline return `warnings`: `ARRIVAL_EVIDENCE_LIMITED` names the modeled paths, when the Circle attestation timing for managed CCTP delivery expires (or that it has expired) and `arrivalModel.expiresAt`, and `ARRIVAL_EVIDENCE_UNAVAILABLE` means the arrival model review has lapsed. Warnings never block saving. The dashboard shows the same coverage and expiry on the policy form, the saved policy and the simulator, and a delivery check that cannot pass explains whether the arrival model or the Circle attestation timing lapsed, the route is composed or a network is unmodeled.

## Continue without a time estimate

If delivery time is unknown and you do not need a deadline, choose a policy with **Lowest total cost** and leave **Maximum delivery time** blank. In Auto-route, also use the **Lowest total cost** preference. Fetch a new comparison, then prepare a route that passes the remaining checks.

Only someone with policy-management access can change or create a policy. Editing a shared policy affects future quotes from every API key assigned to it; choose an existing suitable policy or create a separate one when appropriate. This option relaxes the timing requirement only. Fee limits, recipient amounts, route availability, wallet authorization and transaction safety checks still apply. A missing estimate does not mean instant or guaranteed delivery.

## Unavailable USD prices

Prices identify their market source and upstream observation time. The optional CoinMarketCap fallback uses reviewed numeric market IDs and exact chain/token mappings. USDT0 and legacy USDT retain separate identities. An inactive listing or rejected timestamp does not supply a price. These observations value payment amounts and gas currencies in USD; they do not replace network fee estimates or wallet balance checks.

Route requires fresh observations for the exact asset identity; it never substitutes a stablecoin peg or a similarly named token. `valuation.issues` distinguishes missing mappings (`UNSUPPORTED_PRICE_ASSET`), temporary market-service failures (`PRICE_TEMPORARILY_UNAVAILABLE`), stale observations (`PRICE_STALE`) and rejected or missing market evidence (`PRICE_UNVERIFIED`). Each issue names the affected asset or network fee currency and whether retrying may help. Older saved observations may omit this field.

For a temporary failure, respect `retryAfterSeconds` when present. Refresh the existing payment's checks through its next action; do not allocate or submit another transfer merely because pricing failed. Saved quotes remain immutable: obtaining a new comparison requires a new quote request and its normal credit charge. Non-retryable issues need supported asset coverage or corrected pricing evidence. Missing prices never relax the account owner's USD limits.

Concurrent identical market reads share one request. A rate-limited service is briefly backed off while independent fallbacks remain available. Optional quote caching never extends a price's upstream expiry; preparation and signing retain fresh revalidation. Prices must be younger than five minutes. `issues` is diagnostic: actual payment and fee checks determine which missing prices block a route.

## Require a provider for selected assets

In **Routing policies → Edit policy rules → Add provider rule**, add tokens on the **From** and **To** sides and choose the provider the rule requires. The visual flow shows **From → must use → To**. Circle supports **Fast only**, **Standard only**, or **Fast or Standard**. After choosing a token, select **All networks** or individual networks, for example USDC on every listed network going to native USDC on Stellar. The dashboard saves the exact catalog IDs listed at that moment; networks Route adds later are not included until you edit the rule.

Rules are strict requirements, not preferences. A cheaper NEAR quote cannot override a matching CCTP Fast rule. If the required route is unavailable, disabled, paused, outside your limits or missing required evidence, Route returns no eligible alternative for that rule. Your app can display the failed checks; it must not assume a provider fallback. Quotes still show alternatives with exclusion reasons.

If Route's catalog later removes or stops verifying an asset ID that a rule lists, the rule is not skipped. Every quote that the ID could cover on that asset's network fails the `provider-rule` check with a request to review the rule, including quotes from the required provider, and preparation and later legs are refused the same way. The dashboard marks the asset **Unavailable**. Edit the rule to choose the current catalog asset.

Assets use IDs from `GET /v1/assets`, including the network and exact contract or issuer. Same-symbol representations do not match automatically. An empty source or destination list means **any supported asset on that side**; at least one side must contain an asset. Direction matters: add another rule for the reverse transfer. Every matching rule applies. Contradictory overlapping rules are rejected when saving. The required provider must also appear in the policy's `providers` list.

Use `GET /v1/policy` to read the assigned policy, then `PUT /v1/policy` with its current version and complete limits:

```json
{
  "version": 2,
  "valueCurrency": "USD",
  "priority": "cost",
  "maxFee": "2",
  "maxSeconds": null,
  "minAmount": "1",
  "maxAmount": "1000",
  "providers": ["circle", "near"],
  "providerRules": [
    {
      "id": "usdc-stellar-fast",
      "name": "Native USDC via CCTP Fast",
      "sourceAssetIds": ["ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],
      "destinationAssetIds": ["stellar:nep245%3Av2_1.omni.hot.tg%3A1100_111bzQBB65GxAPAVoxqmMcgYo5oS3txhqs1Uh1cgahKQUeTUq1TJu"],
      "provider": "circle",
      "mode": "fast"
    }
  ]
}
```

Resolve the current asset IDs from the catalog and choose your own limits before sending this example. Each policy supports up to 20 rules and 500 assets per side. A policy update request may be up to 128 KB. An omitted `providerRules` on an update preserves the existing rules; an explicit `[]` removes them. Saving creates a new policy version, so existing unsigned payments require review against current settings.

Each candidate exposes a `provider-rule` check and `providerRule.applied`, with the rule ID, required provider/mode and `payment` or `leg-N` scope. These checks affect `selected`, execution selection and preparation selection, and are enforced again before funding. Rules never waive balance, fee, credit, key or authorization requirements.

Auto-route checks the whole requested pair and each individual leg. A rule on the overall pair requires every leg to use that provider/mode; an aggregator that merely uses CCTP internally does not count as direct `circle`. A rule on an intermediate asset pair applies to that leg. There is no silent switch when advancing to the next leg. Provider rules currently apply to mainnet only; testnet retains its separate CCTP policy and candidate selection.

## Testnet rules

New Testnet policies use `valueCurrency: "TEST_USDC"`, with payment amounts and protocol-fee limits expressed in test USDC. They allow Circle CCTP and compare protocol fees. Source/destination gas and complete arrival timing remain outside that comparison. Quotes still return `selected: null`; select a quoted candidate that is not excluded by policy.

The released testnet flow supports 1–10 test USDC from Ethereum Sepolia to Stellar testnet. Your policy can narrow that range. Preparation rejects a wallet intent whose protocol-fee cap exceeds the policy limit. Test tokens have no USD price, and a successful testnet transfer does not validate mainnet liquidity, prices or delivery deadlines.

## Change or reuse a policy

Open **Routing policies** to select a policy, create another, or edit its rules. A saved edit creates an immutable revision. Every assigned key uses the updated rules on future quotes. Quotes and payments record the policy identity and revision that produced them. Changes to an unrelated policy do not invalidate those records; changes to their own policy can require a fresh quote before new funding. Tracking remains available for existing transfers.

`GET /v1/policy` reads the policy assigned to the calling key; `PUT /v1/policy` updates that same policy with `policy:write` and the issuer’s current permission. Send the current `version` back when saving. Treat it as a concurrency token, not a counter to increment yourself. A key cannot switch its policy: issue a replacement key to change the binding.

Payment and quote reads, retries, preparation, signature, execution and cancellation through an API key require the same policy as the saved record. Rotation within that policy continues to work. Dashboard users retain their role-based project access. Provider connections are project-level resources with separate explicit permissions; policy binding does not turn them into isolated provider accounts. Webhook management still requires the `webhooks:read` or `webhooks:write` scope, but an endpoint created through an API key inherits that key's policy and receives only that policy's payments. Keys list and manage only their own policy's endpoints; project-wide endpoints are managed in the dashboard. See [webhooks](webhooks.md).

## Existing integrations

Existing project rules and API keys are preserved under **Default policy**, labeled as a shared legacy policy for Mainnet and Testnet. Historical revisions and signed payment evidence are unchanged. Legacy USD limits are not reinterpreted as test-USDC limits. A revision saved before USD limits keeps its original USDC-unit values: the dashboard labels them as legacy units that are not applied, mainnet comparisons under it cannot be recommended, and the guided key setup asks you to save its limits in USD before issuing a mainnet key. Editing such a policy asks you to confirm each value as a USD amount before saving. Create separate named network policies for new integrations.

Older dashboard clients that omit `policyId` continue to target the default policy, which must have a saved revision before a new key can be issued. The guided dashboard sends an explicit policy ID and checks provider readiness.

SwapKit is available for connection setup, catalog discovery and cross-chain quotes, with Route-managed or customer API credentials. Supported simple EVM deposits can execute; other transaction types remain quote-only. See [SwapKit coverage and connection options](swapkit.md).

Rift is optional and needs no provider credential. Enable its connection and add `rift` to the intended policy. Supported direct orders require explicit variable-output acceptance at preparation and all wallet and policy checks. Rift estimates have no guaranteed minimum and cannot become an automatic fixed-minimum recommendation or a composed payment leg. Existing policies are unchanged. See [Rift coverage](providers.md#rift).

## Connect your backend

Use `https://route.click/v1` with `Authorization: Bearer YOUR_ROUTE_KEY` and the matching `Route-Network: mainnet` or `testnet` header. Omitting the network selects mainnet; a mismatched key returns `KEY_NETWORK_MISMATCH`. Keep the key in backend secret storage. Browser cookies are not accepted by the customer API. JSON mutations need `Content-Type: application/json`.

Use the [API reference](api-reference.md) for each operation's required scope. Persist the operation's UUID and exact request before making an idempotent mutation. Create a replacement key on the same policy, update your backend, then revoke the old key to rotate access without replacing existing payments.

NEAR and SwapKit offer Route-managed access or your own provider credential. Garden is paused; its saved settings are retained but cannot enable new quotes or execution. Circle, Allbridge, LayerZero, Axelar and Rift do not require a customer provider key. A Route API key is always required for your backend.

## Optional API-key restrictions

Optional controls:

| Control | Meaning |
| --- | --- |
| Maximum per payment | USD value of the source asset amount, using a fresh observed price. Excludes network gas. |
| Rolling limit | Sum of unresolved reservations plus funded payment value in the preceding 24 hours, 7 days or 30 days. These are rolling periods, not calendar boundaries. |
| Providers | Every provider used by the route must be allowed. |
| Source/destination networks | Separate lists for each direction. Composed intermediate legs are checked too. |
| Source/destination assets | Exact catalog IDs, including network and token representation. Symbols alone are insufficient. |
| Recipients | Destination network and address pairs. EVM addresses compare without case; other chain identities retain their case. This is an address restriction, not a memo-based beneficiary approval system. |

Blank limits and unselected lists mean unrestricted by that control. Assigned policy and provider capabilities still apply. Existing keys retain their previous behavior until replaced with restricted keys. A key with policy write permission can change its assigned policy; provider write permission changes shared project connections. It cannot edit its own binding or key restrictions.

## Enforcement

New quotes reject prohibited source/destination identities before adapter calls, and only query providers allowed by both assigned policy and the current key. Composed candidates must also satisfy restrictions on each leg. USD-limited requests fail closed if the exact source asset has no valid price, or if the observation is expired, older than five minutes or implausibly in the future. Stablecoins are not assumed to equal one dollar. Amounts and budgets use decimal/integer arithmetic.

Payment draft creation enforces both the quote's original key and the requesting key. Provider preparation additionally enforces the draft's key and the actual recipient. Preparing through another key or the dashboard cannot remove restrictions inherited from a quote or draft. A preparation preserves the full set of applicable key restrictions. Revoked keys cannot authorize new requests; a replacement assigned to the same policy with sufficient permissions can inspect and track existing instructions without discarding their original restrictions.

Reading saved records and matching retries return existing evidence. They do not allocate another deposit, move funds or reserve a second budget. Keys can read quote and payment records from their assigned policy, including older records created by another key on that policy. Other policies return `KEY_POLICY_MISMATCH`; payment lists are filtered by policy.

## Team access changes

Members limited to specific projects cannot access workspace billing, credit top-ups, team or audit records, or rename the workspace, even with the Admin role. An owner or administrator with access to all projects manages those workspace-wide settings.

Removing a member or reducing their role permanently revokes the API keys they issued in that workspace. Removing a project from a member’s access, including narrowing all-project access to a list, revokes that member’s keys for the removed projects only; their keys for projects they keep continue to work. Restoring membership or project access does not restore old keys; an authorized member must issue a new key. Requests using these revoked keys return HTTP 401 with `KEY_ISSUER_ACCESS_REVOKED`, and the dashboard lists them as revoked because the issuer lost access.

For NEAR payments made with a recipient-restricted key, `refundTo` must be the source sender. This also applies to the first transfer in a composed route; subsequent transfers refund to their own intermediate sender. The restriction is checked again before wallet approval, signing and submission, including preparations created before a key was restricted. A mismatch returns `KEY_REFUND_RESTRICTION`.

## Reservations and recovery

Quotes and review drafts do not consume rolling budget. Before a provider call can allocate deposit instructions, Route reserves the fresh USD source value in the same database transaction as the preparation attempt. Locks serialize budget checks across concurrent requests. Each applicable rolling-limited key gets one reservation per preparation. Failed budget checks roll back the attempt and never call the allocating provider. For SwapKit, the reservation commits with the channel claim, before `/v3/swap` is called. It is kept while the preparation has no deposit instructions, including when the build fails, its outcome is unknown or the channel expires first; there is no release endpoint. The one exception is SwapKit's definite refusal (`409 SWAPKIT_BUILD_REFUSED`), which proves no channel exists: the reservation is released at once and a retry of `/prepare` checks and reserves the budget again.

Uncertain responses keep their reservation, including after the rolling period ends: issued deposit instructions might still receive funds. Retries use the saved attempt. When source funding is verified and finalized, the reservation becomes committed usage; its rolling window begins at Route's first finalized-source observation. A refund still counts as outgoing payment volume. Repeated tracking does not restart the window.

A canonically finalized source revert releases the preparation's reservation together with its payment credits, as does a verified final wallet cancellation or closure of an unfunded payment. A composed payment releases its shared hold only when its first transfer reverts, or is verifiably cancelled, before a second transfer starts; later failures can leave funds at an intermediate step, so the hold remains. Otherwise, uncertain, signed-but-unobserved and intermediate-held work keeps its reservation. There is no time-based or operator release.

A release does not deactivate provider deposit instructions. A NEAR or SwapKit deposit address can still accept a transfer sent outside Route after the payment's source transfer reverts or is cancelled. Route tracks only the saved source transaction, so a later transfer to the same address is not tracked, limited or billed through the original payment. Do not reuse the address; prepare a new payment, which reserves capacity again.

Preparation rechecks USD limits after receiving provider instructions. A rise above the reservation or per-payment limit produces a review blocker and removes the unsigned wallet transaction from readiness. The saved provider instructions remain available for reconciliation. Budget usage is shown in the key list as reserved and recently funded USD values.

## Current boundary

Quote and draft checks apply across all seven adapter families. Execution reservations apply to supported NEAR preparations and protocol actions, including supported SwapKit deposits; Garden is paused. Composed workflows share one rolling principal hold and check restrictions on every leg; see [composed payments](composed-payments.md). [Wallet intent approvals](wallet-approvals.md) recheck inherited restrictions and record consent without authorizing funding. The hosted customer testnet API uses Route keys too, but rejects USD-limited keys because test tokens have no USD valuation. See the [testnet guide](testnet-api.md) for released coverage.

These controls govern Route requests; they cannot stop someone sending funds directly from an independently controlled wallet to a public address. The gated [transaction handoff](payment-transactions.md) now adds final revalidation, conservative reservation increases bound to a saved transaction, and wallet-sequence coordination. Exact wallet signatures authorize released mainnet paths. Current reservation values are preparation-time estimates, not final accounting valuations. The account, quote and supported mainnet execution services are deployed. See [release status](release-status.md) for current availability conditions.

## Access errors

| Error | Meaning |
| --- | --- |
| `400 INVALID_PROVIDER_RULE` | Invalid assets, conflicting rules, or a provider/mode not allowed by the policy. |
| `400 INVALID_KEY_RESTRICTIONS` | Invalid limits, identifiers or lists. |
| `403 FRESH_SIGN_IN_REQUIRED` | Select **Send verification email** in the key form, verify in another tab in the same browser, then return and retry. The current session is still active. |
| `401 KEY_ISSUER_ACCESS_REVOKED` | The issuing member lost access; create a new key with authorized membership. |
| `403 KEY_REFUND_RESTRICTION` | For a recipient-restricted NEAR key, set `refundTo` to the source sender. |
| `403 KEY_POLICY_MISMATCH` | Use a key assigned to the record’s policy. |
| `409 POLICY_REQUIRED` | Save a policy before creating a key or requesting quotes. |
| `403 KEY_RESTRICTION` | A route, recipient or payment value violates a key restriction. |
| `409 KEY_VALUATION_REQUIRED` | A fresh valid source-asset price is unavailable. |
| `409 KEY_BUDGET_EXCEEDED` | Insufficient rolling capacity including unresolved reservations. |
| `409 KEY_POLICY_UNAVAILABLE` | An original restriction record could not be verified. |

## Dashboard session timeout

Dashboard sessions expire after 30 minutes without activity. A warning appears two minutes before expiry; choose **Stay signed in** to continue. Active interaction renews the session, while background refreshes and API calls do not. The server rejects expired sessions even if the browser stays open or sleeps. A session has a maximum lifetime of seven days; sensitive actions still require a recent sign-in.

Inactivity sign-out affects dashboard access only. API keys remain valid under their own expiry and restrictions, and payments already submitted continue to be tracked. Unsaved form edits may be lost. Sign in again to resume dashboard work.


## Pricing identity and reliability

USD policy checks use reviewed network, token identifier and decimal precision. Bridged or pegged representations require their own exact token market; a native asset's price is not a substitute. `UNSUPPORTED_PRICE_ASSET` means no reviewed mapping exists, while a temporary market outage is reported separately. Gas uses the network's native fee asset.

`GET /v1/assets` marks each asset's `usdPricing`. An `unsupported` asset has no reviewed mapping, so USD policy checks for routes to or from it stay unresolved and Route never recommends or prepares them. `reviewed` covers only the asset's own price identity: each quote still needs a fresh market price, and the fee check also needs the source network's fee estimate priced in that network's native fee asset, which Route does not yet have for every network. Assets that previously borrowed a canonical asset's price without their own reviewed market are now `unsupported` until each is reviewed: NEAR-bridged ETH, BTC (nBTC) and FRAX; Solana USD1; Starknet XRP; Aptos BTC, ETH, SOL, XRP, LINK, UNI and AAVE; and both HyperCore USDC representations.

Cost-first policies without a delivery deadline may select a route with recent delivery failures. Such candidates expose `reliabilityWarnings`; the dashboard shows the warning inside the recommendation, wallet-check or execution-unavailable card that presents the route (or beside its recommended-quote line when another route fills those cards) and on the route's comparison row. This does not change the owner's cost preference. Speed and deadline checks still require usable end-to-end timing, and degraded timing cannot satisfy them.