> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Access and permissions
> Understand how organization, environment, read, write and credential bound every MCP connection.
An MCP connection never receives blanket access to the account. Its reach is made of four explicit decisions:
| Layer | What it defines |
| ------------ | -------------------------------------------------- |
| Credential | Who is connecting: a user via OAuth, or an API key |
| Organization | The single organization the connection can reach |
| Environment | Test, live or both |
| Access | Read only, or read and write, in each environment |
Beyond these layers, every operation must be granted to the connection and, under OAuth, the user must still hold access and the required capability in the organization.
Authorization is revalidated on every call. Revoking a connection, an API key,
an environment or the user's access affects the next operation, without
waiting for the client's token to expire.
## Enabling per environment
An administrator controls MCP under **Developers → Connections**:
| Environment | Initial state | Recommended use |
| ----------- | ------------- | ---------------------------------------------- |
| Test | Enabled | Development, prompt validation and automations |
| Live | Disabled | Operating on real data, after review |
Disabling an environment immediately blocks every scope pointing at it. The connection stays listed and the scope stays visible, but calls return `environment_disabled`.
## OAuth or API key
| Behavior | OAuth | Organization API key |
| ------------ | ---------------------------------- | ----------------------------------------- |
| Sign-in | Browser | Bearer token |
| Organization | Chosen during consent | Fixed by the key |
| Environments | Test, live or both | One environment, fixed by the key |
| Access | Set separately per environment | Derived from the key's scope |
| Identity | The current user | An automation credential |
| Revalidation | The user's access and capabilities | The key's validity, environment and scope |
| Best for | Assistants used by people | Scripts, CI and agents with fixed context |
## OAuth
The client discovers authentication from `https://mcp.chargefy.io` and opens Chargefy's official screen.
### Choosing the organization
Every OAuth session belongs to **one organization**. If you belong to several, pick one during consent. To use another organization, revoke the session and connect again selecting the new one.
That separation keeps a natural-language request from silently switching between accounts.
### Choosing access per environment
For the selected organization, each enabled environment offers three options:
* **No access**;
* **Read only**;
* **Read and write**.
Enabled environments start preselected as **read only**. Writing requires an explicit choice.
You can authorize:
* test only;
* live only;
* test and live with different access levels.
When only one environment is in scope, the tools infer `livemode`. If both test and live are authorized, pass it:
```json theme={"theme":"css-variables"}
{
"livemode": false
}
```
Use `false` for test and `true` for live. The organization is already pinned to the connection and does not need to be repeated in normal use.
### Write capabilities
Selecting "read and write" sets the ceiling of the scope. The operation still depends on the user's current capability:
| Resources | Required capability |
| ---------------------------- | ------------------- |
| Customers | `customer.write` |
| Products and prices | `product.write` |
| Discounts and discount codes | `discount.write` |
| Payment links | `payment.create` |
If the capability is missing, reads keep working and the change returns `missing_capability`.
### Granting operations
During consent, Chargefy records which operations that connection may execute. That record is what makes the agent's exact reach explainable and auditable.
If the MCP surface gains an operation after authorization, it does not slip silently into existing connections. Authorize again when you want to grant the new method.
## API key
Use an organization API key when the context must be fixed and predictable.
```text theme={"theme":"css-variables"}
Authorization: Bearer {{API_KEY}}
```
The key defines:
* the organization;
* the environment, through the `ch_test_` or `ch_live_` prefix;
* the reach: `read`, `write` or `admin`;
* expiry and revocation.
That is why an API-key connection needs neither `organization` nor `livemode`.
### Key scopes
| Scope | Behavior in MCP |
| ------- | -------------------------------------------------------------------- |
| `read` | Exposes reads only; the write tools do not appear |
| `write` | Exposes reads and the low-risk writes |
| `admin` | Same MCP reach as `write`; administrative actions remain unavailable |
Platform keys scoped `platform_admin` are rejected. MCP operates one
organization per connection and accepts organization keys only.
## Two protections for writes
### Confirmation in the client
The agent should show the operation and the data before a meaningful change when you ask for confirmation. That review belongs to the client or to workspace policy.
The server does not open a new confirmation screen on every call. Writing is
split into two tools so the annotation can be honest: `chargefy_api_create` is
additive and `chargefy_api_update` is announced as destructive
(`destructiveHint`), because it changes an existing record. Clients that respect
the annotation ask for confirmation before each update and usually run creates
without a per-call confirmation.
### Idempotency with `intent_id`
Every execution through `chargefy_api_create` or `chargefy_api_update` requires an opaque `intent_id` of 16 to 64 characters. A UUID is a good choice.
```json theme={"theme":"css-variables"}
{
"arguments": {
"data": {
"email": "name@email.com"
},
"intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
"operation": "customers.create"
},
"name": "chargefy_api_create"
}
```
Rules:
* generate a fresh value for each intended change;
* on a timeout or transport failure, repeat the same request with the same `intent_id`;
* the replay returns the original result instead of executing again;
* reusing the token with another operation or other data returns a conflict;
* reads do not use `intent_id`.
## Revoking or reducing access
### OAuth
Under **Developers → Connections**, you can:
* **update the permissions** of the session;
* revoke the test or the live scope;
* revoke the whole session;
* reconnect to change organization or access levels.
Authorizing the same client again syncs the selection: removed environments lose access, and switching organization revokes the previous organization's scopes.
#### Updating permissions
When Chargefy publishes new methods, sessions already connected keep the set you authorized — nothing is added without your approval. The session is flagged as **Update available**, and the **Update permissions** action recalculates access within what you already authorized: same organization, same environment, same access level. Before applying, you see exactly what comes in and what goes out.
The same action also **reduces** access: methods that depend on a permission you lost leave the session, and scopes for organizations you can no longer reach are revoked. To widen the reach — another organization, another environment, or moving from read to write — reconnect and consent again.
### API key
Revoke the key under **Developers → API keys**. Revoking the credential is the definitive cut for a token-based connection.
If a key shows up in a commit, log, screenshot, conversation or shared
history, treat it as compromised. Revoke it and create another one.
## Recommended practices
* Start in test, read only.
* Keep test and production connections separate when using API keys.
* Grant writes only for the period and the client that need them.
* Review the application's name and domain before approving OAuth.
* Do not put API keys in version-controlled files.
* Ask for human confirmation before writes with operational impact.
* Review unused connections under **Developers → Connections**.
## Access errors
| Code or situation | What it means | How to resolve |
| ------------------------ | --------------------------------------------------------- | ------------------------------------------------------------- |
| Missing or invalid token | The sign-in expired or the credential was revoked | Authenticate again or use another key |
| `no_scope` | There is no active scope, or the environment is ambiguous | Check `get_chargefy_account_info`; pass `livemode` if needed |
| `environment_disabled` | MCP is turned off for that environment | Enable the environment under **Developers → Connections** |
| `org_access_revoked` | The OAuth user lost access to the organization | Review the user's membership or reconnect |
| `write_not_allowed` | The environment was authorized for reading only | Reauthorize with write access or use a suitable key |
| `missing_capability` | The user cannot change that kind of resource | Grant the required capability or keep the operation read-only |
| `operation_not_granted` | The connection was not granted that operation | Authorize again and review the scope |
| Unsupported key | A platform key was used | Use OAuth or an organization API key |
## Keep going
See the full catalog and the arguments of each tool.
Apply the access model to queries and safe writes.