# Organisation and system scope

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



DALP evaluates authenticated API requests inside one organisation context. Deployed resources also use one system context. Keep API keys, system addresses, roles, and environment configuration in sync so your integration reads and writes only the resources it is allowed to use.

## 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 organisation that owns the integration workload. Use separate keys for separate organizations.                                               |
| Organisation               | Which off-chain records, users, API keys, and organisation-owned resources are visible | Confirm the API key was created while the intended organisation was active. If a user belongs to more than one organisation, do not reuse one organisation key for another organisation. |
| 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 operations 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 administration.                               |

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

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

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

For integrations:

1. Create a separate key per organisation.
2. Store the key with the organisation and environment it belongs to.
3. Rotate or revoke a key from the same organisation context that created it.
4. Rotate or recreate legacy keys that fail because they do not resolve an active organisation.
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 organisation 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.

## Requests without organisation context [#requests-without-organisation-context]

Some authenticated endpoints need an organisation before they return data. If the caller has no resolved organisation, DALP either returns an empty result for unavailable state or rejects the operation with the endpoint's documented error response. A resource identifier does not select a different organisation by itself.

Before calling organisation-scoped endpoints from a background worker or service account, verify that the API key belongs to the intended organisation and that the worker configuration carries the matching system address when the endpoint is system-specific.

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

For organisation- 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 organisation,
* the resource belongs to another system,
* the caller does not have permission to view it.

When debugging a `404`, verify the organisation-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 organisation,
* the key is stored separately for each organisation 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 organisation and system configuration as the read paths they depend on.

## Related guides [#related-guides]

* [Getting started](/docs/api-reference/reference/getting-started)
* [Request headers](/docs/api-reference/reference/request-headers)
* [Operational integration patterns](/docs/api-reference/reference/operational-integration-patterns)
* [Error handling](/docs/api-reference/errors/error-handling)
* [Add administrators](/docs/developers/platform-setup/add-admins)