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

# API Access and Scopes

> How to use API keys, publishable keys, scopes, and API playground safely in production

# API Access and Scopes

This guide explains API access from a workspace operator perspective.

## Key types and intent

Linquid typically uses two key categories:

* Workspace API keys for server-side automation and management operations.
* Publishable keys for client-safe tracking and SDK workflows.

Many workspaces also use API Applications (OAuth clients) for partner-facing app integrations that need client ID/secret, redirect URIs, and optional PKCE enforcement.

## Credential class separation

| Credential type       | Intended usage                       | Must not be used for                 |
| --------------------- | ------------------------------------ | ------------------------------------ |
| Workspace API key     | Server-side privileged automation    | Browser/client-exposed code          |
| Publishable key       | Client-safe tracking                 | Privileged management operations     |
| OAuth app credentials | External app authorization workflows | Internal all-purpose automation keys |

## Scope strategy

Use narrow scopes by default.

Recommended pattern:

1. one key per integration/service
2. least-privilege scope set
3. dedicated rotation owner
4. immediate disable on decommission

## Scope lifecycle process

1. Define exact operations required by the integration.
2. Create dedicated key with minimal scope set.
3. Test in non-critical workflow path.
4. Promote to production usage.
5. Rotate periodically and after incidents.

## Common scope families

Workspace API access is typically segmented into:

* link and campaign management scopes
* routing/rule management scopes
* analytics read scopes
* webhook/integration management scopes
* billing/workspace administration scopes

Use separate keys for read-only analytics jobs vs write-capable automation.

## API playground usage

Use the API playground for:

* understanding request/response shape
* validating payload structure before coding
* testing scope behavior in sandbox-safe conditions

Operational safety:

* do not store long-lived privileged keys in shared notebooks.
* avoid testing destructive operations in production workspaces.
* log ownership for every key/app credential.

## OAuth application controls

For API applications:

* keep redirect URI list minimal and exact
* require PKCE for public clients
* rotate client secret on credential exposure risk
* disable/delete unused apps promptly

OAuth app user experience typically includes an authorize/consent step where end users approve requested scopes for the connected application.

Operational guidance:

1. keep requested scopes minimal and understandable.
2. keep redirect targets tightly controlled.
3. review denied vs approved authorize outcomes during integration rollout.

## Key rotation and incident response

| Scenario                        | Immediate action                        | Follow-up action                               |
| ------------------------------- | --------------------------------------- | ---------------------------------------------- |
| Suspected key leak              | Disable key, generate replacement       | Audit recent key activity and affected systems |
| Integration provider compromise | Rotate related keys and webhook secrets | Validate all outbound/inbound integrations     |
| Stale key still active          | Disable key and notify owner            | Update credential inventory and ownership      |

## Operational controls

* track key usage and last-seen activity
* remove unused keys regularly
* separate production and testing credentials
* avoid reusing one broad key across all systems

## Common failure modes

* wrong workspace context for a key
* missing scope for an operation
* using publishable key for privileged operations
* stale/rotated key still used by external automation

## Public vs privileged key usage

* Publishable keys are for client-safe tracking contexts only.
* Workspace API keys are for privileged server-side operations.
* Never swap these roles in production integration design.

## Monthly access-key checklist

1. Review all active keys and owners.
2. Disable keys with unknown ownership.
3. Validate key scopes against current integration need.
4. Rotate high-risk and aging credentials.
5. Re-test critical integrations after rotation.

Related:

* `/user-guides/manual/workspace/workspaces-and-access`
* `/user-guides/manual/workspace/security-and-compliance`
* `/user-guides/manual/workspace/workspace-tabs-and-plan-gates-reference`
* API Reference -> Workspaces -> API Keys, Usage, and Billing