# Quick Start — First Kiteworks API Call in 10 Minutes

> Make your first Kiteworks REST API call in under 10 minutes. Step-by-step Python guide: authenticate with OAuth 2.0, list top-level folders, and read the response.

Getting Started

# Quick Start — Your First Kiteworks API Call in Python

In this guide you'll authenticate against your Kiteworks instance and make your first API call — listing your top-level folders — using a single Python script. The whole thing takes about 10 minutes.

## Before you start

Confirm the following before running any code:

1

API license is enabled

In the Kiteworks Admin console, go to **Application Setup → Licenses** and confirm the API row shows **Enabled**. See [Before You Begin → Check your license status](before-you-begin.html#check-license) for details.

2

Custom application created

You have a registered application with its **Client Application ID** and **Client Secret Key** saved securely. See [Before You Begin → Register a new application](before-you-begin.html#create-app-steps) if you haven't done this yet.

3

Python environment ready

Python 3.8+ is installed, along with the `requests` and `pywebview` packages.

4

`get_access_token.py` is in your working directory

Copy the `KWOAuthClient` implementation from the [Authentication → Python sample](authentication.html#ac-python) and save it as `get_access_token.py` in the same folder as the script you're about to write.

## What you'll build

A single Python script that authenticates against your Kiteworks instance using the Authorization Code flow and prints a list of your top-level folders — their names, IDs, and paths. Those folder IDs are the starting point for everything else in the API: listing files, uploading, creating subfolders, and more.

## Step 1 — Authenticate

`KWOAuthClient` handles the full Authorization Code flow for you: it opens a browser window for the Kiteworks login page, captures the authorization code after you sign in, exchanges it for an access token, and caches the token locally so subsequent calls don't require re-authentication until the token expires.

Create a new file called `quick_start.py` and start with these three lines:

quick_start.py Copy

```python
from get_access_token import KWOAuthClient

base_url = "https://your.kiteworks.domain"  # replace with your instance URL
client = KWOAuthClient(base_url)
```

When you run the script, `KWOAuthClient` will prompt you for your `client_id` and `client_secret` in the terminal, then open a browser window for you to sign in. After you authenticate, it captures the token automatically — you won't need to handle the redirect manually.

> Never hard-code your `client_id` or `client_secret` in source code. In production, load them from environment variables or a secrets manager.

## Step 2 — List your top-level folders

Now add the API call. `GET /rest/folders/top` returns all root folders accessible to the authenticated user. Add this to `quick_start.py`:

quick_start.py Copy

```python
import requests

access_token = client.get_access_token()

response = requests.get(
    f"{base_url}/rest/folders/top",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "28",
        "Content-Type": "application/json",
    }
)
response.raise_for_status()
folders = response.json()

print(f"Found {len(folders)} top-level folder(s):\n")
for folder in folders:
    print(f"  {folder['name']}")
    print(f"    ID:   {folder['id']}")
    print(f"    Path: {folder['path']}")
    print()
```

## The complete script

Here's everything together. Save this as `quick_start.py` in the same directory as `get_access_token.py`, then run it with `python quick_start.py`.

quick_start.py Copy

```python
import requests
from get_access_token import KWOAuthClient

# ── Configuration ────────────────────────────────────────────────
# Replace with your Kiteworks instance URL.
# client_id and client_secret will be prompted at runtime.
BASE_URL = "https://your.kiteworks.domain"

# ── Step 1: Authenticate ─────────────────────────────────────────
# KWOAuthClient opens a browser for sign-in, captures the token,
# and caches it so subsequent calls skip re-authentication.
client = KWOAuthClient(BASE_URL)
access_token = client.get_access_token()

# ── Step 2: List top-level folders ───────────────────────────────
response = requests.get(
    f"{BASE_URL}/rest/folders/top",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "28",
        "Content-Type": "application/json",
    }
)
response.raise_for_status()
folders = response.json()

# ── Step 3: Print the results ────────────────────────────────────
print(f"Found {len(folders)} top-level folder(s):\n")
for folder in folders:
    print(f"  {folder['name']}")
    print(f"    ID:   {folder['id']}")
    print(f"    Path: {folder['path']}")
    print()
```

## Step 3 — Read the result

A successful run prints output like this:

terminal output Copy

```bash
Found 3 top-level folder(s):

  My Folder
    ID:   b111c222-d333-e444-f555-a666777888bbb
    Path: My Folder

  Shared Projects
    ID:   c222d333-e444-f555-a666-b777888999ccc
    Path: Shared Projects

  Archive
    ID:   d333e444-f555-a666-b777-c888999000ddd
    Path: Archive
```

Each folder has three key fields:

| Field | What it means |
|---|---|
| `name` | The display name of the folder as it appears in Kiteworks. |
| `id` | The folder's UUID. This is the value you'll pass as `folder_id` or `parent_folder_id` in every subsequent API call that involves this folder. |
| `path` | The full path to this folder. For top-level folders the path equals the name; for nested folders it shows the complete hierarchy (e.g. `My Folder/Reports/2026`). |

> You've made your first authenticated Kiteworks API call. The folder IDs in this output are your starting point for everything else — navigating subfolders, listing files, uploading, and creating new folders.

### Something went wrong?

| Error | Likely cause |
|---|---|
| `401 Unauthorized` | The access token is missing or has expired. Delete any cached token state and re-run the script to trigger a fresh sign-in. |
| `403 Forbidden` | The token does not have the scope needed to read folders, or the API license is not enabled. Check your application's registered scopes in the Admin console. |
| Browser window doesn't open | `pywebview` may not be installed, or your environment doesn't support a GUI (e.g. a headless server). Install with `pip install pywebview` or run the script in a local desktop environment. |
| Empty folder list | The authenticated user has no top-level folders accessible to them. Sign in with an account that has folder access, or create a folder in the Kiteworks web app first. |

For a full reference on API status codes and error responses, see [API Concepts → HTTP Status Codes](api-concepts.html#status-codes).

## Frequently Asked Questions

### How long does it take to make a first Kiteworks API call?

Most developers make their first successful API call within 10 minutes, assuming they have a licensed Kiteworks instance and a registered custom application. The main steps are: obtain an access token, then send a GET request to `/rest/folders/top`.

### Does the Kiteworks API support languages other than Python?

Yes. The Kiteworks REST API is language-agnostic — any HTTP client can call it. This guide uses Python for its readability, but the same patterns apply to JavaScript, Java, Go, Ruby, and any other language with an HTTP library.

### What does GET /rest/folders/top return?

`GET /rest/folders/top` returns a JSON array of the top-level folders your access token has permission to see. Each folder object includes an `id`, `name`, type, and permission metadata. Use the `id` from this response to navigate into child folders or list files.

### How do I attach a Kiteworks access token to API requests?

Include the access token in the HTTP `Authorization` header as a Bearer token: `Authorization: Bearer <access_token>`. This header must be present on every API request except the token endpoint itself.

## What's next

Now that you have folder IDs and a working authentication setup, here's where to go:

[Manage Folders

Navigate into subfolders, list their contents, and create new folders using the IDs from this guide.](manage-folders.html)

[Manage Files

List, search, download, and upload files using the folder IDs you just retrieved.](manage-files.html)

[Authentication

Understand how KWOAuthClient works, token refresh, and the JWT flow for server-side integrations.](authentication.html)

[API Concepts

Learn how pagination, sorting, rate limits, and error responses work across every endpoint.](api-concepts.html)