# Getting started Source: https://docs.settlemint.com/docs/developer-guides/api-integration/getting-started Create an API key, configure the DALP TypeScript SDK, and choose the right API, CLI, or OpenAPI path for authenticated integration. The DALP API is the programmatic entry point for organisation-scoped asset operations. Start here when you need a machine client that can authenticate, call the OpenAPI REST surface, and then route to the right API page for asset lifecycle, compliance, wallet, settlement, monitoring, webhook, or error-handling work. API keys are organisation credentials. They inherit the creating user's DALP permissions, carry a read or read-write scope, and authenticate REST requests with `X-Api-Key`. Use one key per organisation or environment so reporting jobs, settlement automation, and asset operations do not share the same blast radius. ## Choose the right API path [#choose-the-right-api-path] | If you need to | Start with | Then read | | --------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Make your first authenticated REST call | Create an API key and generate a TypeScript client below. | [SDK integration](/docs/developer-guides/api-integration/sdk) and [API reference](/docs/developer-guides/api-integration/api-reference) | | Keep organisations, systems, and environments separated | Create one key for the active organisation. | [Organisation and system scope](/docs/developer-guides/api-integration/organization-system-scope) | | Send calls on behalf of a participant or execution wallet | Configure the shared headers only on routes that support them. | [Request headers](/docs/developer-guides/api-integration/request-headers) and [smart wallets](/docs/developer-guides/api-integration/smart-wallets) | | Automate asset lifecycle operations | Use a read-write key and verify the target token workflow first. | [Token lifecycle](/docs/developer-guides/api-integration/token-lifecycle), [token holders and transfers](/docs/developer-guides/api-integration/token-holders-transfers), and [external tokens](/docs/developer-guides/api-integration/external-tokens) | | Wire compliance, documents, monitoring, or webhooks | Keep the key scope narrow and route each job to the matching reference page. | [Compliance modules](/docs/developer-guides/api-integration/compliance-modules), [KYC document uploads](/docs/developer-guides/api-integration/kyc-document-uploads), [API monitoring](/docs/developer-guides/api-integration/api-monitoring), and [webhook endpoints](/docs/developer-guides/api-integration/webhook-endpoints) | ## Prerequisites [#prerequisites] Before creating an API key: 1. Have a running DALP instance, either hosted or local. 2. Sign in to the platform UI with an account that belongs to the target organisation. 3. Select the organisation that should own the API key. The key stores that organisation context. 4. Confirm your account has the role permissions needed for the operations you plan to call. A read-only key can call safe HTTP methods. Mutations require a read-write key. API key authentication skips interactive wallet verification. Browser session authentication still requires wallet verification on write operations that ask for it. ## API integration model [#api-integration-model] ## Create an API key [#create-an-api-key] ### Step 1: Navigate to API Keys page [#step-1-navigate-to-api-keys-page] 1. Click your profile avatar in the top right corner 2. Select **API Keys** from the dropdown menu ![API Keys page](./_assets/api-keys-page.webp) ### Step 2: Generate a new key [#step-2-generate-a-new-key] 1. Click **Create API Key** 2. Enter a descriptive name (e.g., "Production Integration", "CI/CD Pipeline") 3. (Optional) Set an expiry date - keys without expiry remain valid until manually revoked 4. Click **Create** ### Step 3: Copy and secure your key [#step-3-copy-and-secure-your-key] The platform displays your API key **once**. Copy it immediately and store it securely (environment variable, secret manager, password vault). **Key format**: `sm_dalp_xxxxxxxxxxxxxxxx` **Important**: If you lose the key, you cannot recover it. Revoke the old key and create a new one. ### Step 4: Review key settings [#step-4-review-key-settings] Your API key has: * **Permissions**: Inherits your user role permissions (check with `systemAccessManagerRolesList()`) * **Organization scope**: Locked to the organization active when you created the key * **Access scope**: Choose `read-write` for integrations that create or update DALP resources. Choose `read` for reporting jobs that only call safe HTTP methods (`GET`, `HEAD`, or `OPTIONS`). Read-only keys cannot use write methods such as `POST`, `PUT`, `PATCH`, or `DELETE`. * **REST API access**: API keys authenticate REST requests. They are not accepted on `/api/rpc`. Use REST endpoints for API-key based integrations. * **Metadata**: Stores `organizationId` and access scope for session context ### Managing API keys [#managing-api-keys] From the API Keys page you can: * **View active keys** - Name, expiry date * **Delete keys** - Permanently revoke access (cannot be undone) *** ## Configure the SDK [#configure-the-sdk] The recommended TypeScript path is the `@settlemint/dalp-sdk` package. It uses the DALP API contract directly, sends authenticated calls to `/api/v2`, and adds the API key as the `x-api-key` request header. ```bash npm install @settlemint/dalp-sdk dnum zod ``` Or with Bun: ```bash bun add @settlemint/dalp-sdk dnum zod ``` The SDK requires `zod >= 4.0.0`. The examples below also use `dnum` for token amounts, so install both packages explicitly with the SDK. ### Create a client [#create-a-client] ```ts import { createDalpClient } from "@settlemint/dalp-sdk"; const dalp = createDalpClient({ url: "https://your-platform.example.com", apiKey: process.env.DALP_API_KEY, }); ``` Use the deployment origin as `url`. Do not append `/api`; the SDK normalises the base URL and calls the current REST API under `/api/v2`. For multi-organisation setups, pass the active organisation explicitly when the integration must pin every request to one organisation: ```ts const dalp = createDalpClient({ url: "https://your-platform.example.com", apiKey: process.env.DALP_API_KEY, organizationId: "org_xxx", }); ``` ### Test your connection [#test-your-connection] Verify authentication with a safe read before running mutations: ```ts const tokens = await dalp.token.list({ query: {} }); console.log("Token count:", tokens.data.length); ``` If the call succeeds, the API key is accepted and the client can reach the DALP API. If it fails with `UNAUTHORIZED`, check the key value and expiry. If it fails with `FORBIDDEN`, check the user's role and the key scope. ### When to use the OpenAPI specification [#when-to-use-the-openapi-specification] Use the SDK for TypeScript services. Use the OpenAPI specification when you need to generate a client in another language, import the API into a gateway, or inspect the REST contract directly. ```bash curl https://your-platform.example.com/api/v2/spec.json \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" ``` The current API specification is served at `/api/v2/spec.json`. Legacy integrations can still inspect `/api/v1/spec.json` where required. The interactive reference for the current REST API is available under `/api/v2` on the DALP deployment. ### Common errors [#common-errors] For complete error handling guidance, see the [Error handling guide](/docs/developer-guides/api-integration/error-handling). **Quick fixes:** * **401 Unauthorized** - API key is invalid or expired. Check the key includes the `sm_dalp_` prefix and is enabled in the API Keys page. * **403 Forbidden** - Your user account lacks permissions. See [Platform setup](/docs/developer-guides/platform-setup/add-admins) for role management. * **404 Not Found** - Check that `url` is the DALP deployment origin without an added `/api` suffix and that the deployment is running. *** ## Authentication header formats [#authentication-header-formats] DALP accepts API keys in following header format: **X-Api-Key** (recommended): ```http X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx ``` *** ## Wallet verification for write operations [#wallet-verification-for-write-operations] When authenticating with an **API key**, wallet verification is **not required**. You can omit the `walletVerification` field entirely: ```ts import { from as dnumFrom } from "dnum"; // API key auth: no walletVerification needed await dalp.token.mint({ params: { tokenAddress: "0xABCD..." }, body: { recipients: ["0x1234..."], amounts: [dnumFrom("1000", 18)], }, }); ``` When authenticating with a **session cookie** (browser-based), write operations still require wallet verification: ```ts // Session-based auth: walletVerification required await dalp.token.mint({ params: { tokenAddress: "0xABCD..." }, body: { recipients: ["0x1234..."], amounts: [dnumFrom("1000", 18)], walletVerification: { verificationType: "PINCODE", secretVerificationCode: "123456", // Your 6-digit PINCODE }, }, }); ``` **Why the difference?** API keys are scoped, rate-limited credentials designed for machine-to-machine use. The key is the authorization factor, so an interactive second challenge is unnecessary. Session-based authentication still requires wallet verification as a second factor to prevent unauthorized transactions from a compromised session. *** ## CLI and AI agent integration [#cli-and-ai-agent-integration] The CLI follows the same authentication model. `dalp login` opens the browser device flow, creates a read-write API key for the CLI, and stores the credential locally. Use `dalp logout` when you need to revoke that CLI key and clear the local credential. For scripts and AI agents, prefer CLI commands that return structured output: ```bash dalp login --url https://your-platform.example.com dalp whoami --format json dalp auth org-list --format json ``` Use the CLI when an operator or agent needs a supported command surface. Use the SDK when your application needs direct TypeScript calls. Use OpenAPI when another language or gateway needs the REST contract. For MCP and skill-file setup, see [AI agent integration](/docs/developer-guides/cli/ai-agents). *** ## API architecture [#api-architecture] The DALP API is built on **oRPC**, which provides: * **Type-safe client generation** - Auto-generated TypeScript clients with full IntelliSense support * **Automatic OpenAPI documentation** - Explore endpoints, schemas, and examples at `/api/v2` for the current API version * **Schema validation** - Requests and responses validated against Zod schemas * **Custom serializers** - BigInt, BigDecimal, and Timestamp types serialized correctly over JSON * **Transaction headers** - Blockchain mutations return `X-Transaction-Hash` in response headers for easy tracking * **Streaming support** - Long-running operations return progress updates via server-sent events All endpoints follow RESTful conventions with `POST` for mutations, `GET` for queries, and standardized error codes (401 for auth failures, 403 for permission denials, 404 for missing resources). *** ## Next steps [#next-steps] Now that your client is configured: 1. **[Review organization and system scope](/docs/developer-guides/api-integration/organization-system-scope)** to keep API keys, organizations, systems, and environments separated 2. **[Review the token lifecycle](/docs/developer-guides/api-integration/token-lifecycle)** to understand operation flows 3. **[Set up roles](/docs/developer-guides/platform-setup/change-admin-roles)** to grant yourself system and token permissions 4. **Choose an asset guide** and deploy your first token: * [Bonds](/docs/developer-guides/runbooks/create-mint-bonds) * [Deposits](/docs/developer-guides/runbooks/create-mint-deposits) * [Equities](/docs/developer-guides/runbooks/create-mint-equities) * [Funds](/docs/developer-guides/runbooks/create-mint-funds) * [Stablecoins](/docs/developer-guides/runbooks/create-mint-stablecoins) For API reference documentation and OpenAPI spec, see [API reference](/docs/developer-guides/api-integration/api-reference).