> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create an API key, send it correctly, and scope it to only what it needs.

Every request to the Dashlink API needs an API key. There is no session, no OAuth flow, and no token exchange.

## Sending your key

Put the key in the `X-API-Key` header:

```bash cURL theme={null}
curl https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks \
  -H "X-API-Key: dlk_live_..."
```

```javascript Node.js theme={null}
const headers = { "X-API-Key": "dlk_live_..." };
```

```python Python theme={null}
headers = {"X-API-Key": "dlk_live_..."}
```

```go Go theme={null}
req.Header.Set("X-API-Key", "dlk_live_...")
```

```ruby Ruby theme={null}
headers = { "X-API-Key" => "dlk_live_..." }
```

```php PHP theme={null}
$headers = ['X-API-Key: dlk_live_...'];
```

> [!WARNING]
>
> **`Authorization: Bearer` does not work.** It is a natural thing to try, and it fails with a `401` that does not explain why. The request is rejected by the framework layer before it reaches Dashlink, because a Dashlink key is not the kind of token that header is checked against. Use `X-API-Key`.

### Query parameter fallback

`?api_key=dlk_live_...` also authenticates, for contexts where you cannot set a header.

> [!WARNING]
>
> Prefer the header. Query strings are written to server access logs, proxy logs, browser history, and the `Referer` header of any outbound link on the page — none of which you control, and all of which retain the key long after the request.

## Creating a key

**1. Open the dashboard**

Go to **Settings → API Keys** in the [Dashlink dashboard](https://app.dashlink.ai).

**2. Create the key**

Give it a name describing where it will be used — `zapier-production`, `internal-reporting` — so you can revoke the right one later without guessing.

**3. Choose a type**

**REST API** (`dlk_live_`) for dashboard endpoints. **Dynamic Link** (`dlk_sdk_`) for the native SDK. A Dynamic Link key cannot call REST; a REST key cannot authenticate JSON resolve.

**4. Choose a scope and permissions**

See below. Narrower is better. Dynamic Link keys are locked to **All** for resolve and tracking only.

**5. Copy it now**

The key is shown once. Dashlink stores only a SHA-256 hash of it, so it genuinely cannot be shown again — if you lose it, you create a new one and revoke the old.

## Key format

REST keys:

```
dlk_live_<86 characters>
```

Dynamic Link SDK keys:

```
dlk_sdk_<86 characters>
```

Around 95 characters in total. The prefix tells you which surface the key can reach: `dlk_live_` for `/api/v1`, `dlk_sdk_` for JSON resolve only. A Dynamic Link key on REST returns `401`. A REST key on edge JSON resolve returns `401`.

## Types

| Type | Prefix | Reaches |
| - | - | - |
| REST API | `dlk_live_` | Dashboard API (`/api/v1/*`) |
| Dynamic Link | `dlk_sdk_` | App Dynamic Link JSON resolve and tracking only |

Create the type in Settings → API Keys → Type. Scope (organization vs self) is a separate field.

## Scopes

A key's scope decides whose data it can reach.

| Scope | Reaches |
| - | - |
| `self` | Only resources owned by the user who created the key |
| `organization` | Every resource in the organization |

Most integrations want `organization`, because links created by a departed colleague should not fall out of your integration's view.

## Permissions

Permissions decide what the key can do.

> [tab] all
>
> Read and write across every module. Convenient, and the right choice only when the integration genuinely does everything.

> [tab] read\_only
>
> Read across every module, write nowhere. The right default for reporting, dashboards, and anything that only observes.

> [tab] restricted
>
> Per-module grants. The right choice for everything else.

### Restricted keys

A restricted key is granted a permission level per module:

| Module | Covers |
| - | - |
| `shortlinks` | Shortlinks and app dynamic links |
| `qrcode` | QR codes |
| `campaigns` | Campaigns and channels |
| `analytics` | All analytics and reports (read-only) |
| `domains` | Custom domains and platform subdomains |
| `utm_templates` | UTM templates |
| `dynamic_link_templates` | Dynamic Link templates |
| `tags` | Tags |
| `organization` | Organization profile and members |

Levels are `read`, `write` and `all`, in increasing order — `write` implies `read`, and `all` implies both.

> [!NOTE]
>
> App dynamic links are Shortlinks underneath, so they are covered by the `shortlinks` grant rather than a module of their own.

> [!NOTE]
>
> `analytics` accepts only `read`. There is no analytics write path, so a `write` grant there would promise something that does not exist.

A key for a reporting tool that reads links and their analytics and changes nothing:

```json theme={null}
{
  "permission_type": "restricted",
  "permissions": [
    { "module": "shortlinks", "permission_level": "read" },
    { "module": "analytics", "permission_level": "read" }
  ]
}
```

## When authentication fails

| Status | `code` | Means |
| - | - | - |
| `401` | `AUTHENTICATION_REQUIRED` | No key sent, or the key is malformed, expired or revoked |
| `403` | `PERMISSION_DENIED` | Key is valid, but not allowed to do this |

A `403` on a restricted key almost always means the module grant is missing or is `read` where the call needs `write`.

## Keeping keys safe

> [accordion] REST keys never in apps
>
> A dashboard REST key (`dlk_live_`) in a browser or APK can mutate the workspace. Call REST from your backend. The exception is a **Dynamic Link** key (`dlk_sdk_…`): it must live in the app so JSON resolve can authenticate, and it cannot call REST.

> [accordion] Use separate keys per integration
>
> One key per system means revoking a compromised key takes down one integration rather than all of them, and access logs tell you which system did what.

> [accordion] Grant the narrowest permission that works
>
> A reporting key with `read_only` cannot delete your links even if the code that holds it has a bug.

> [accordion] Rotate by overlapping
>
> Create the new key, deploy it, confirm traffic has moved, then revoke the old one. Revoking first means downtime.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.