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

# Authentication

> When you need an API key, how to get one, and the scopes it can hold.

Most Multiliquid API routes are public. A user's wallet signature authorizes swaps, redemptions, and batch orders, and the data and discovery routes need no credential. A credential identifies an organization: it raises the rate allowance, attributes submissions and redemptions to the organization, unlocks the organization's own lists, and authorizes capital provider operations.

## Credentials

| Credential | Used by | Accepted on |
| - | - | - |
| None | Any client | Every public route |
| Customer API key | An organization's integrations and servers | Public routes, the capital provider routes, `GET /v1/organization`, and the organization's delegate list, subject to the key's [scopes](#scopes) |
| Account session | The Multiliquid app, for a signed-in member | Every route |

A credential is sent as a bearer token in the `Authorization` header:

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/batch-orders/payloads?network=evm-mainnet" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY"
```

A credential in the query string, such as `?api_key=`, is an unknown query parameter. The request is rejected with `400` and code `INVALID_REQUEST`, not `401`, and the message points to the `Authorization` header.

A supplied credential never falls back to anonymous access. A credential that fails authentication receives `401` with code `UNAUTHORIZED` and the header `WWW-Authenticate: Bearer`. A valid credential without access receives `403`: code `INSUFFICIENT_SCOPE` when an API key lacks the operation's scope, `ORGANIZATION_NOT_SELECTED` when an account session selects no organization, on any route it is sent to, or `FORBIDDEN` when the credential has no access to the organization, the resource, or the operation, such as another organization's capital provider or a member's session on a route only admins may use.

`GET /v1/organization` returns the organization a credential acts for, its `id` and `name`, for any API key or an account session that selects an organization; a session that selects none receives `403` with code `ORGANIZATION_NOT_SELECTED`. [Delegates](https://docs.multiliquid.xyz/api-reference/capital-providers/delegates.md#your-organization-id) shows it.

## API keys

Access is by invitation. Once Multiliquid has invited an organization, its members sign in to the Multiliquid account area at [carry.multiliquid.xyz/account-management](https://carry.multiliquid.xyz/account-management) and manage API keys there. Organizations without access request it from their Multiliquid contact.

* The key's secret is shown once, when the key is created. A lost secret cannot be recovered, so the key is revoked and replaced.
* A key has no expiry unless one is chosen when it is created.
* Each key carries one or more [scopes](#scopes), chosen when it is created. A key never gains a scope later; a personal key loses `cp:admin` when its owner is demoted.
* Rotating a key means creating a replacement with the same scopes, moving the integration to it, and then revoking the old key.

### Personal and organization keys

A key is owned by one member or by the organization.

| Property | Personal key | Organization key |
| - | - | - |
| Created by | Any member, for themselves | An admin only |
| Scopes | At most the scopes the owner's current role permits. Created without a choice of scopes, it receives every scope the creator's role permits. | Chosen explicitly when it is created, and fixed afterward |
| When people change | Loses `cp:admin` when its owner is demoted from admin, and is revoked when its owner leaves the organization | Unaffected by its creator or any other member leaving or being demoted |
| Listed and revoked by | Its owner, and any admin | Admins only |
| Counts toward | Its owner's 10 active keys in the organization, and the organization's 100 | The organization's 100 active keys only |
| Rate allowance | Its user's and its organization's 600 requests a minute | Its organization's 600 requests a minute only, shared with every other credential of the organization |
| Stops working when | Its owner or an admin revokes it, it expires, its owner's membership or account ends, or the organization is suspended or deleted | An admin revokes it, it expires, or the organization is suspended or deleted |

An organization key, also called a service key, suits a server integration that must keep working when the people who set it up change roles or leave. Expired and revoked keys do not count toward either limit.

## Scopes

A scope grants one kind of access. An integration holds only the scopes it uses, so a key that leaks can do no more than its job requires.

| Scope | Grants | Roles that can grant it |
| - | - | - |
| `read` | The organization's private data: its submission and redemption lists, the `receiver` of its redemptions, its capital providers and their orders, attempts, payloads, and requirements, its delegate list, and each delegate's on-chain admin state | Members and admins |
| `trade` | Acting for users under the organization's name: credentialed submissions and redemptions, which are recorded under the organization | Members and admins |
| `cp:operate` | A capital provider's daily work: posting batch capacity, reporting order outcomes, and registering Solana nonce accounts | Members and admins |
| `cp:admin` | Selecting or clearing a capital provider's operator, and preparing delegate admin transactions | Admins only |

An account session holds every scope its member's role permits: a member's session holds `read`, `trade`, and `cp:operate`, and an admin's also `cp:admin`.

### Scope by route

| Route | Scope an API key needs |
| - | - |
| `GET /v1/batch-orders/capital-providers`, `GET /v1/batch-orders/capital-providers/orders`, and `GET /v1/batch-orders/{orderId}/attempts` | `read` |
| `GET /v1/batch-orders/payloads` and `GET /v1/batch-orders/batches/{batchId}/requirements` | `read` |
| `GET /v1/organization` | Any scope, with a personal or organization key |
| `GET /v1/organizations/{organizationId}/delegates` and `GET /v1/organizations/{organizationId}/delegates/{delegateId}/admin/state` | `read` |
| `GET /v1/submissions`, and `GET /v1/redemptions` with a credential and neither `user` nor `redemptionId` | `read` |
| `POST /v1/submissions` and `POST /v1/redemptions` with a credential | `trade` |
| `PUT /v1/batch-orders/capital-providers/{capitalProviderId}/capacity` | `cp:operate` |
| `POST /v1/batch-orders/{orderId}/reports` | `cp:operate` |
| `POST /v1/batch-orders/nonce-accounts` | `cp:operate` |
| `PUT` and `DELETE /v1/batch-orders/capital-providers/{capitalProviderId}/operator` | `cp:admin` |
| `POST /v1/organizations/{organizationId}/delegates/{delegateId}/admin/prepare` | `cp:admin` |

`GET /v1/redemptions/{redemptionId}` and `POST /v1/redemptions` show the `receiver` of the organization's own redemptions only to a credential with `read`. A key without it is not rejected there; the response omits `receiver`. On the other public routes, such as quotes, builds, and the data routes, a key of any scope only moves the request to the credentialed rate allowance.

A key without a route's scope receives `403` with code `INSUFFICIENT_SCOPE`, and nothing changes:

```json theme={null}
{
  "error": "API key lacks the required scope",
  "status": 403,
  "code": "INSUFFICIENT_SCOPE",
  "details": { "requiredScope": "cp:operate" },
  "requestId": "req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f"
}
```

> [!WARNING]
>
> A credentialed `POST /v1/submissions` or `POST /v1/redemptions` whose key lacks `trade` is rejected with `INSUFFICIENT_SCOPE`. It is not accepted as an anonymous request. An integration that submits on behalf of users either holds a key with `trade` or sends those requests without a credential.

## Organization attribution

A credentialed submission or redemption is recorded under the credential's organization, and the organization can then list its own:

* `GET /v1/submissions?network=` lists the organization's [submissions](https://docs.multiliquid.xyz/api-reference/swap/submissions.md#organization-submissions). It requires a credential, and an API key needs the `read` scope.
* `GET /v1/redemptions` with a credential and neither `user` nor `redemptionId` lists the organization's [redemptions](https://docs.multiliquid.xyz/api-reference/treasury/lifecycle.md#organization-redemptions) in full. An API key needs the `read` scope for this list; a lookup by `user` or `redemptionId` needs no scope.

A capital provider's batch order routes show the orders placed with its own capital providers, as [Batch operations](https://docs.multiliquid.xyz/api-reference/capital-providers/batch-operations.md) describes.

## Rate allowances

A request with a credential is authenticated before it runs and is not counted against its IP address. A personal key or account session counts against 600 requests a minute for its user and 600 a minute for its organization; an organization key counts against the organization's allowance alone. On the [counted routes](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md#counted-routes), each `401` for a supplied credential spends one of the client IP address's 30 failed authentications a minute. [Rate limits](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md) gives every allowance.

## Related

> [card] [Errors](https://docs.multiliquid.xyz/api-reference/guides/errors.md)
>
> `UNAUTHORIZED`, `FORBIDDEN`, `INSUFFICIENT_SCOPE`, and every other code.

> [card] [Capital providers](https://docs.multiliquid.xyz/api-reference/capital-providers/overview.md)
>
> The routes that `read`, `cp:operate`, and `cp:admin` unlock.


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