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

# Getting API access and credentials

> How API access is turned on for your account and how your API keys are issued.

You cannot create API keys yourself, and there is no key page in the Bullionwale app yet. Bullionwale turns on API access for your account and issues the keys.

Test keys are available on request. Production keys are not issued while production trading is switched off: see the availability notice on the [introduction](/index).

## Ask for access

Contact your Bullionwale relationship manager or the Bullionwale desk and ask for:

1. **API access for your account.** Without it every call is refused with `403 api_access_disabled`.
2. **A test key** to build and test your integration. Start here even if you only plan to trade in production.
3. **The scopes the key needs** (see [Scopes](#scopes)). To place orders, ask for `orders:write`.
4. Optionally, an **expiry date** for the key, and a **name** that tells you which of your systems uses it (for example `order-bot`). The name comes back as `key_name` from `GET /me`.

A **live** key for production is a separate request, made when you meet the [production access requirements](/production-access).

## Receive and store the key

<Warning>
  **The full key is shown once,** when it is created or rotated. Bullionwale cannot show it to you again; it can only replace it. Store it in a secret manager straight away.
</Warning>

A key is one string with four parts separated by dots:

| Environment | Key shape |
| - | - |
| Test | `bwk_test.<broker>.<key id>.<secret>` |
| Production | `bwk_live.<broker>.<key id>.<secret>` |

* `bwk_test` or `bwk_live` says which environment the key works in.
* The **key id** is public. `GET /me` returns it as `key_id`, and it is safe to quote when you talk to Bullionwale about a key.
* The **secret** is the last part. Never share it, including with Bullionwale staff.

Keep keys out of source code, URLs, browser or mobile app code, logs and tickets. If a key may have leaked, ask Bullionwale to revoke it at once (see [Credentials](/credentials#revocation)).

## Send the key

Send the key on every call in the `X-API-Key` header:

```bash theme={null}
curl -s https://api.bullionwale.com/api/trading/test/v1/me \
  -H "X-API-Key: $BULLIONWALE_API_KEY"
```

* A test key works only on the test paths (`/api/trading/test/v1`), and a live key only on the production paths (`/api/trading/v1`). The other combination is refused with `401 wrong_environment`.
* Your web or mobile login is never accepted by this API, and an API key is never accepted by the web or mobile app.

## Scopes

A key carries scopes that decide which calls it may make:

| Scope | Allows |
| - | - |
| `account:read` | `GET /me` |
| `orders:read` | `GET /orders`, `GET /orders/{order_id}`, `GET /positions` |
| `orders:write` | `POST /orders` |
| `rates:read` | Reserved for a future live-rates call. No call uses it today. |

A new key gets `account:read`, `rates:read` and `orders:read` unless you ask otherwise. `orders:write` is granted only when you ask for it. A call that needs a scope the key lacks is refused with `403 insufficient_scope`.

A read-only key (without `orders:write`) is a good choice for dashboards and reconciliation jobs that never place orders.

## How many keys

Each account can have a limited number of active keys per environment (five by default; Bullionwale's limit may differ). Use separate keys for separate systems, so that one can be rotated or revoked without touching the others.

## Check a key

`GET /me` shows the account and key behind the `X-API-Key` header, the key's scopes, and `production_trading_available`. Run it whenever you install a new key. See the [quickstart](/quickstart) for an example.


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