API Keys & Developer Access

API keys are the credentials that let your code talk to Linkzly. Instead of using your account password, you create a dedicated key for each application, script, or integration. Each key carries exactly the permissions it needs — nothing more — so you can share keys with services and teammates without exposing your full account access.

You would use API keys when you want to:

Create or manage short links programmatically from your own application
Pull analytics data into a dashboard or reporting tool
Trigger QR code generation as part of an automated workflow
Integrate Linkzly into a CI/CD pipeline or internal tool

Navigate to API Keys under the Management section in the left sidebar to manage all your keys.

The page header displays the title "API Keys" with the subtitle "Manage API access for external applications" and three buttons in the top right:

API Docs — opens the API reference at /dashboard/api-keys/docs
Test API Key — opens the key tester at /dashboard/api-keys/test
Create API Key — navigates to the creation page at /dashboard/api-keys/create (permission-gated; disabled when your plan limit is reached)

15.1 Creating an API Key

Click Create API Key to navigate to the creation page. The page is organized into three tabs: Basic Settings, Permissions, and Advanced. A sidebar on the right provides the API Key Format reference and Quick Setup presets.

Tab 1 — Basic Settings

Field	Required	Description
Key Name	Yes	A descriptive label so you know what this key is used for. Placeholder: `Production API Key`.
Expiration Date	No	A future date and time after which the key stops working. Leave empty for no expiration.
Description	No	Internal notes about the key's purpose, such as which system uses it or who created it. Placeholder: `API key for mobile application backend integration`.

Tab 2 — Permissions

The Access Permissions section lists six permission categories. Select the individual checkboxes for exactly the access this key requires.

Category (UI Label)	Available Permissions	Scope Strings
Short Urls	Read Short Urls, Create/Update Short Urls, Delete Short Urls	`links:read`, `links:write`, `links:delete`
Analytics	View Analytics	`analytics:read`
QR Codes	View QR Codes, Create/Update QR Codes, Delete QR Codes	`qrCodes:read`, `qrCodes:write`, `qrCodes:delete`
Domains	View Domains, Manage Domains, Delete Domains	`domains:read`, `domains:write`, `domains:delete`
Webhooks	View Webhooks, Manage Webhooks	`webhooks:read`, `webhooks:write`
Deeplinks	View Deeplinks, Manage Deeplinks, Delete Deeplinks	`smartLinks:read`, `smartLinks:write`, `smartLinks:delete`

Select only the scopes the key actually needs. You can update scopes later by editing the key.

Sidebar presets — the Quick Setup card provides three one-click preset buttons to pre-fill common permission sets:

Read-Only Access — grants read scopes across all resources
Full Access — grants all available scopes
Analytics Only — grants analytics:read only

Tab 3 — Advanced

Rate Limiting section:

Field	Description
Request Limit	Maximum number of requests per period. Default: `1000`. Must be a positive integer.
Time Period	Dropdown: `per minute`, `per hour` (default), `per day`.

IP Allowlist section:

Field	Description
Allowed IP Addresses	Multi-tag input. Enter each IP address and press Enter. Supports CIDR notation. Example: `192.168.1.1`, `203.0.113.0/24`. If empty, requests are accepted from any IP.

Origin Allowlist section:

Field	Description
Allowed Origins (CORS)	Multi-tag input. Enter each origin URL and press Enter. Example: `https://example.com`. If empty, no origin restriction is applied.

Note on origin allowlisting: The Allowed Origins (CORS) field is available in the UI and values are saved, but CORS origin validation is not currently enforced at the API middleware level. Only IP allowlisting is actively enforced on every request.

After Creation — API Key Created Dialog

After clicking Create API Key, a dialog titled "API Key Created" appears. This dialog displays the full, unhashed API key value — this is the only time the key is shown. The dialog includes:

A red alert: "This is the only time you'll see this API key. Store it securely."
The key name label and the full key value in a copy-enabled code block
A Copy button to copy the key to your clipboard
An "I've copied the key" button to close the dialog

Copy the key to a secure location — such as your application's environment variables or a secrets manager — before closing.

15.2 API Key Permissions (Scopes)

Permissions are stored as colon-separated strings in the format resource:action. When calling the API, Linkzly checks that the key holds the required scope for each endpoint.

Full scope reference:

Resource	Scope	Description
Short Urls	`links:read`	View and list all short links
Short Urls	`links:write`	Create and modify short links
Short Urls	`links:delete`	Delete short links
QR Codes	`qrCodes:read`	View QR code data and settings
QR Codes	`qrCodes:write`	Generate and modify QR codes
QR Codes	`qrCodes:delete`	Remove QR codes
Domains	`domains:read`	View domain configurations
Domains	`domains:write`	Add and configure custom domains
Domains	`domains:delete`	Remove custom domains
Analytics	`analytics:read`	Access analytics data and reports
Webhooks	`webhooks:read`	View webhook configurations
Webhooks	`webhooks:write`	Create and manage webhooks
Deeplinks	`smartLinks:read`	View smart link and deep link data
Deeplinks	`smartLinks:write`	Create and modify smart links
Deeplinks	`smartLinks:delete`	Remove smart links

15.3 API Key Format

Linkzly issues two types of keys depending on the environment:

Type	Format	Use
Live key	`lzly_live_[32-character string]`	Use in production environments. Actions taken with a live key affect real data.
Test key	`lzly_test_[32-character string]`	Use for development and testing.

The key value is constructed from a prefix (lzly_live_ or lzly_test_) followed by a 32-character nanoid. Only the key part (everything after the prefix) is hashed and stored in the database; the prefix is stored in plaintext and used to generate the masked display identifier.

Masked display format: After creation, the dashboard shows the key in masked form: lzly_live_xxxxxxxx•••xxxx (the prefix followed by ••• and the last four characters). This is the Key Preview shown in the keys table and is not secret — it is only used for visual identification.

Important — Key shown only once: The complete key value is displayed only in the "API Key Created" dialog immediately after creation. Once you close that dialog, the full key cannot be recovered. If you lose it, you must regenerate the key, which immediately invalidates the old one.

15.4 API Key Security

The following actions are available from the Actions column in the keys list and from the key edit page.

Edit

Opens the edit page at /dashboard/api-keys/[id]/edit. You can update the key name, description, expiration date, rate limit settings, allowed IPs, and allowed origins. Permissions can also be updated on an existing key via the same three-tab interface used during creation.

Not available for revoked keys.

Regenerate

Creates a new key secret and immediately invalidates the old key value. Any application using the old key will receive 401 Unauthorized errors until updated.

A confirmation dialog states: "This will create a new key for '[name]'. The current key will stop working immediately."

After confirming, the "API Key Created" dialog appears with the new key value. Copy it before closing.

Warning: Regenerating a key breaks all services currently using the old value. Update the key in every application before confirming.

Available for active, non-revoked keys only.

Revoke

Immediately and permanently disables the key. A revoked key returns 401 Unauthorized on all requests.

A confirmation dialog states: "The API key '[name]' will be permanently revoked and cannot be reactivated. This action cannot be undone."

Important: Revocation is permanent. A revoked key records a revokedAt timestamp and cannot be reactivated. If you need to re-enable API access, create a new key.

Available for active keys only.

Activate

Re-enables an inactive key that has not been formally revoked. The key returns to active status and resumes accepting requests.

Not available for keys with a Revoked status (see Revoke above).

Delete

Soft-deletes the key and its associated logs. A confirmation dialog states: "This will permanently delete '[name]'. This action cannot be undone."

15.5 Key Management Dashboard

Keys List

The API Keys page shows a searchable, filterable table of all keys in your organization.

Filters and search:

Search — placeholder: "Search API keys..."
Status filter — options: "All Status", "Active", "Inactive"
Sort by — options: "Created Date", "Name", "Last Used", "Usage"
Sort order — ascending or descending toggle

Table columns:

Column	Description
Name	The key name (bold), permission count (secondary text), and truncated description
Key Preview	Masked key in `prefix•••lastFour` format with a copy-on-hover button
Status	`Active` (default badge), `Inactive` / `Revoked` (destructive badge), or `Expired` (secondary badge)
Usage	Total request count, displayed as "X requests"
Rate Limit	The configured limit, displayed as "1000/hour"
Created	The date the key was created
Last Used	Date and originating IP ("from [IP]"), or "Never"
Expires	Expiration date, or "Never"; shown in red if already expired
Actions	Buttons for Edit, Analytics, Revoke/Activate, Regenerate, and Delete

Empty state: "No API keys found. Click 'Create API Key' to get started."

Plan Limits

Each plan has a maximum number of API keys. The Create API Key button is disabled when you have reached your plan limit. Approximate defaults:

Plan	Maximum Keys
Free	~5
Starter	~10
Professional	~50
Enterprise	Unlimited

15.6 Usage Statistics

Click Analytics in the Actions column, or navigate directly to /dashboard/api-keys/[id], to view a breakdown of how the key is being used.

The analytics page has four tabs. Use the time range selector at the top to filter all tabs: "Last 24 hours", "Last 7 days", "Last 30 days", "Last 90 days", or a custom date range via the date picker.

Tab 1 — Overview

Four summary cards:

Metric	Description
Total Requests	All requests made with this key in the selected time range
Success Rate	Percentage of requests that returned a 2xx response
Avg Response Time	Mean response time in milliseconds
Failed Requests	Count of non-2xx responses

Tab 2 — Endpoints

A table of the endpoints called with this key:

Column	Description
Endpoint	The API path called (e.g., `POST /links`)
Method	HTTP method shown as a badge
Requests	Total call count for this endpoint
Success Rate	Percentage of 2xx responses for this endpoint
Avg Response Time	Mean response time for this endpoint

Tab 3 — Errors

A table of error responses grouped by status code:

Column	Description
Status Code	HTTP status code shown as a badge
Count	Number of times this status code was returned

Tab 4 — Logs

A detailed per-request log table:

Column	Description
Timestamp	Exact date and time of the request
Endpoint	The API path that was called
Method	HTTP method
Status	HTTP response code
Response Time	Duration in milliseconds
IP Address	Originating IP address

Note on daily/monthly request counters: The requestsToday and requestsThisMonth counters exist in the database schema but are not automatically reset. The reliable usage metric is Total Requests as tracked in the analytics tabs above.

15.7 API Key Activity Logs

Every request made with a key is logged in detail. Access the full log from the Logs tab on the analytics page.

Each log entry captures: timestamp, endpoint, HTTP method, status code, response time, IP address, user agent, referrer, geographic location, and error details where applicable.

15.8 Test API Key Interface

Navigate to Test API Key from the top-right button on the API Keys page, or go directly to /dashboard/api-keys/test, to validate any API key without making a live data request.

Paste the API key value into the input field.
Submit to run the validation.

The interface displays:

Success: The key is valid. Shows the key name, assigned permissions, and current status.
Failure: A detailed error message explaining why the key was rejected — for example, the key is revoked, expired, or does not exist.

This is useful for confirming that a newly created or regenerated key is working correctly before deploying it to a production environment.