# Organization and system scope

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/organization-system-scope
Understand how DALP API requests are bounded by organization membership, API key scope, active system context, and resource visibility.



DALP evaluates API access in the caller's organization and system context.
Use this page when you design integrations that run across multiple organizations, systems, or environments.

## Scope layers [#scope-layers]

| Layer                      | What it controls                                                                       | What integrators should do                                                                                                                                                               |
| -------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key or session         | Who is making the request and which platform permissions apply                         | Create machine-to-machine API keys from the organization that owns the integration workload. Use separate keys for separate organizations.                                               |
| Organization               | Which off-chain records, users, API keys, and organization-owned resources are visible | Confirm the API key was created while the intended organization was active. If a user belongs to more than one organization, do not reuse one organization key for another organization. |
| System                     | Which deployed system, chain, and system-owned resources are in scope                  | Use the system address or system-specific endpoint required by the API operation. Treat system addresses as part of the integration configuration.                                       |
| Wallet ownership and roles | Which wallet-backed actions the caller can perform                                     | Assign the required platform role and on-chain role before calling write operations such as issuance, role changes, minting, transfers, or administrative actions.                       |

## API keys are organization-scoped [#api-keys-are-organization-scoped]

Newly created API keys are tied to the organization active when the key is created. Requests made with that key run with the associated user's role in that organization.

Legacy API keys that do not carry an organization scope may be rejected by organization-scoped API operations. DALP does not fall back to a global view when a key cannot resolve an active organization. Rotate or recreate those keys from the intended organization before using them for organization-scoped integration traffic.

For integrations:

1. Create a separate key per organization.
2. Store the key with the organization and environment it belongs to.
3. Rotate or revoke a key from the same organization context that created it.
4. Rotate or recreate legacy keys that fail because they do not resolve an active organization.
5. Avoid sharing a key between customer environments, test environments, or operating teams.

## System-scoped requests [#system-scoped-requests]

Many DALP resources belong to a specific deployed system on a specific chain. Examples include issued tokens, token events, holders, system roles, factories, add-ons, and system-level settings.

For those requests, the API combines the caller's organization context with the active system context. A request can only read or act on resources that match both contexts and the caller's permissions.

Practical integration pattern:

```ts
const organization = "acme-production";
const systemAddress = "0x1234...";

// Store both values in your integration configuration.
// Use the organization-specific API key with endpoints that target this system.
```

When you move the same integration between test and production, update both the API key and the system address. Do not point a production API key at a test system or reuse a test key against production resources.

## Missing resources and unauthorized resources [#missing-resources-and-unauthorized-resources]

For organization- and system-scoped resources, DALP avoids exposing whether a resource exists outside the caller's allowed scope. A request for a resource the caller cannot access can return the same not-found style response as a request for a resource that does not exist.

This means a `404` can mean any of the following:

* the resource identifier is wrong,
* the resource belongs to another organization,
* the resource belongs to another system,
* the caller does not have permission to view it.

When debugging a `404`, verify the organization-specific API key, the system address, the chain or environment, and the caller's roles before assuming the resource is absent.

## Integration checklist [#integration-checklist]

Before deploying an integration, confirm:

* the API key was created in the intended organization,
* the key is stored separately for each organization and environment,
* the integration is configured with the correct system address,
* the caller has the required platform role and on-chain role for the operation,
* read paths handle not-found responses without treating them as proof that a resource does not exist globally,
* write paths use the same organization and system configuration as the read paths they depend on.

## Related guides [#related-guides]

* [Getting started](/docs/developer-guides/api-integration/getting-started)
* [Operational integration patterns](/docs/developer-guides/api-integration/operational-integration-patterns)
* [Error handling](/docs/developer-guides/api-integration/error-handling)
* [Add administrators](/docs/developer-guides/platform-setup/add-admins)