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

# API & merchant accounts

The API is fully merchant-account aware, which means that every transaction, buyer, payment method,
and most other resources are accessed within the context of a specific merchant account.

<Note>
  Support for multiple merchant accounts in one instance is a premium feature.
  In a standard instance, all your API calls are associated with the
  `default` merchant account without any extra effort.
</Note>

## Managing accounts

Merchant accounts can be [managed via the dashboard](./accounts) as well as via the [API](/reference/merchant-accounts).

## API keys

API keys can only be created by administrators via the dashboard, they cannot be managed via the API. Keys can
be created to either have access to a specific merchant account, or to all merchant accounts. These so-called
**administrator keys** can be used to make API calls on behalf of any merchant account. Restricted API keys, or **merchant keys**,
can only be used to make API calls on behalf of the merchant account they are associated with.

|              | Administrator keys                               | Merchant keys                         |
| ------------ | ------------------------------------------------ | ------------------------------------- |
| **Access**   | All merchant accounts                            | One merchant account                  |
| **Header**   | Optional, defaults to `default`                  | Defaults to account associated to key |
| **Use case** | Platforms calling the API on behalf of merchants | Merchants making their own API calls  |

## Merchant account header

Most API endpoints can only access and operate on records in one merchant account at a time. Every request
is processed within the context of that one merchant account, and it only allows for using other
resources from within the same merchant account.

For example, an API call to create a transaction associates that transaction with the merchant account
for which the request is made, and it can only use buyers, payment methods, connections,
and flow rules that belong to the same merchant account.

To identify the merchant account to use, set the `X-GR4VY-MERCHANT-ACCOUNT-ID` header. For example,
the following request fetches a list of buyers for the `legendary-games-uk` account
on the `legendary-games` instance.

```sh theme={"system"}
curl https://api.sandbox.legendary-games.gr4vy.app \
  -H "X-GR4VY-MERCHANT-ACCOUNT-ID: legendary-games-uk"  \
  -H "AUTHORIZATION: bearer [token]"
```

<Note>
  In a single merchant instance, the `X-GR4VY-MERCHANT-ACCOUNT-ID` header can be
  omitted and the API falls back to the `default` merchant account ID.
  Additionally, when using a merchant key the header can be omitted and the
  API falls back to the merchant account associated with the key.
</Note>

## Administrator APIs

A few endpoints are not merchant aware and therefore can only be accessed by administrator keys. The only public endpoints
currently affected are the [`GET /api-logs`](reference/logs/list-api-error-logs) endpoint. Setting the
`X-GR4VY-MERCHANT-ACCOUNT-ID` on this API has no effect.

## SDK usage

Each of the SDKs supports setting the merchant account ID. This automatically sets the `X-GR4VY-MERCHANT-ACCOUNT-ID`
for each request to this value. Without setting the ID explicitly its value falls back to `default`.

<CodeGroup>
  ```csharp C# theme={"system"}
  var sdk = new Gr4vySDK(
      id: "example",
      server: SDKConfig.Server.Sandbox,
      bearerAuthSource: Auth.WithToken(privateKey),
      merchantAccountId: "my-merchant-id"
  );
  ```

  ```go Go theme={"system"}
  s := gr4vy.New(
  	gr4vy.WithID("example"),
  	gr4vy.WithServer(gr4vy.ServerSandbox),
  	gr4vy.WithSecuritySource(withToken),
  	gr4vy.WithMerchantAccountID("my-merchant-id"),
  )
  ```

  ```java Java theme={"system"}
  Gr4vy sdk = Gr4vy.builder()
          .id("example")
          .server(AvailableServers.SANDBOX)
          .merchantAccountId("my-merchant-account-id")
          .securitySource(new BearerSecuritySource.Builder(privateKey).build())
      .build()
  ```

  ```php PHP theme={"system"}
  $sdk = Gr4vy\SDK::builder()
      ->setId('example')
      ->setServer('sandbox')
      ->setSecuritySource(Auth::withToken($privateKey))
      ->setMerchantAccountId('your-merchant-account-id')
      ->build();
  ```

  ```python Python theme={"system"}
  sdk = Gr4vy(
      id="spider",
      merchant_account_id="merchant-12345",
      bearer_auth=auth.get_token(private_key)
  )
  ```

  ```ts TypeScript theme={"system"}
  const gr4vy = new Gr4vy({
      server: "sandbox",
      id: "example",
      merchantAccountId: 'merchant-12345',
      bearerAuth: withToken({ privateKey }),
  });
  ```
</CodeGroup>