Organisation and system scope in the DALP API

Every authenticated API request runs inside one organisation context. Resources you deploy also belong to one system context. Keep your API keys, system addresses, roles, and environment settings in sync so your integration reads and writes only what it is allowed to access.

Scope layers

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

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:

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

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

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

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,
• you do not have permission to view it.

When debugging a 404, verify the organisation-specific API key, the system address, the chain or environment, and your assigned roles before assuming the resource is absent.

Integration checklist

Before deploying, confirm each of the following items:

• 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 queries they depend on.

Related guides

• Getting started
• Request headers
• Operational integration patterns
• Error handling
• Add administrators