> For the complete documentation index, see [llms.txt](https://docs.nlx.ai/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nlx.ai/platform/developers/agentic-cx-designer-sdk/getting-started.md).

# Getting Started

## Prerequisites

* An Agentic CX Designer workspace with an Administrator role
* Access to Agentic CX Designer Studio (Admin Hub)

## Authentication

ACXD SDK uses API key authentication. To get an API key you need a programmatic user.

### Step 1: Create a Programmatic User

Programmatic users are machine identities that can authenticate with the ACXD SDK. Only account administrators can create them.

1. In Agentic CX Designer Studio, navigate to Admin Hub > Programmatic Users
2. Click **Create Programmatic User**
3. Provide a name and an optional description
4. Assign permissions via Role Configuration

#### Role Configuration

Each programmatic user has a roleConfig that determines their access:

**Account-level role** 

Grants full access across all workspaces in the account.

```
{
      "roleConfig": {
        "accountRole": "administrator"
      }
  }
```

**Workspace-scoped roles**

Grants specific permissions per workspace

```
{
    "roleConfig": {
      "workspaceRoles": [
        { "workspaceId": "your-workspace-id", "roleId": "role-uuid" }
      ]
    }
  }
```

Workspace-scoped users can be assigned pre-defined roles (administrator, developer, content manager, read-only) or a custom role configured under Roles in Admin Hub.

### Step 2: Generate an API Key

Once a programmatic user exists, generate an API key for it:

1. In Admin Hub → Programmatic Users, select your user
2. Click Generate API Key
3. Copy the full key immediately, it is shown only once

The key format is: `acxd_live_<prefix>.<secret>`

**Important:** Store your API key securely. It cannot be retrieved after creation. You can generate up to 2 keys per programmatic user.

### Step 3: Install the SDK

```
npm install @amazon-connect/agentic-cx-designer-sdk
```

### Step 4: Make your First Call

With your API key and workspace ID, you can make requests to the ACXD SDK.&#x20;

```
import { AgenticCXDesignerClient, ListContextAttributesCommand } from '@amazon-connect/agentic-cx-designer-sdk';
  
const client = new AgenticCXDesignerClient({
  apiKey: 'acxd_live_...',
  workspaceId: 'your-workspace-uuid', // required for workspace-scoped operations
});

const response = await client.send(new ListContextAttributesCommand({}));
console.log(response.items);
```

For account-level operations (e.g., managing programmatic users, workspaces), workspaceId is not required.

### Permissions

The API key is just a credential - it carries no permissions itself. Permissions are resolved at request time from the programmatic user's assigned role. If the role is updated in Admin Hub, the change takes effect immediately.

#### Next Steps

* [**API Reference**](/platform/developers/agentic-cx-designer-sdk/api-reference.md)**:** Explore all available operations
* [**Concepts**](/platform/developers/agentic-cx-designer-sdk/concepts.md)**:** Understand workspaces, applications, and flows
* [**Error Handling**](/platform/developers/agentic-cx-designer-sdk/common-errors.md)**:** Handle errors and retries gracefully


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nlx.ai/platform/developers/agentic-cx-designer-sdk/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.