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

# Best practices

> Guidelines for authentication, destructive calls and reliable integrations.

## Authentication

* Use API keys (`lk_live_...`) for server-to-server integrations. never expose them in client-side code
* Store API keys in environment variables, not in source code
* Rotate keys regularly from **Settings → Developer → API Keys**
* Give each integration its own named key so you can revoke it independently

## Workspace Resolution

When using an API key you do **not** need to pass `x-workspace-id`. the key already encodes the workspace. Only include the header if you want to explicitly validate which workspace you're operating in. Passing an `x-workspace-id` that doesn't match the key's workspace returns a `401`.

## Error Handling

* Always check the HTTP status code before reading the response body
* For `403` errors, check whether the account has hit a plan limit or the API key lacks the required role
* For `409` (conflict), the short code or domain already exists. use a different value

## Retries

* Retry `5xx` errors and network timeouts with exponential backoff
* Do not retry `4xx` errors. they indicate a problem with the request itself
* Add jitter to retry delays to avoid thundering-herd problems

## Security

* Use HTTPS only. the API does not accept plain HTTP
* Never log raw API keys or JWT tokens
* Scope each key to the minimum required workspace and revoke unused keys


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