---
order: 9
slug: "/docs/v1/start/authentication"
title: "Authentication"
section: "Start here"
description: "Choose the correct public App ID, activation token or scoped developer API key and keep management secrets on trusted servers."
audience: "all"
level: "beginner"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/start/quickstart","/docs/v1/start/glossary"]
draft: false
---
Use a [public App ID](/docs/v1/start/glossary#public-app-id) for [activation](/docs/v1/start/glossary#activation), an [activation token](/docs/v1/start/glossary#activation-token) for an installation, and a [developer API key](/docs/v1/start/glossary#developer-api-key) only for server-side management.

## What you will learn
- Compare the three credential types.
- Create, [scope](/docs/v1/start/glossary#scope), rotate and revoke a management key.
- Respond to a leaked key without exposing more [customer](/docs/v1/start/glossary#customer) data.

## Prerequisites
- Read [core concepts](/docs/v1/start/core-concepts) and [environments](/docs/v1/start/environments).
- Use a verified workspace for dashboard actions.

## Credential comparison
| Credential | Who uses it / where it [lives](/docs/v1/start/glossary#live) | Shippable? | Scope and lifetime | Rotation |
| --- | --- | --- | --- | --- |
| Public App ID, app_ | App configuration; [Products](/docs/v1/start/glossary#product) card | Yes; not a secret | Identifies a product shared across environments; activation also needs a key and environment | No secret rotation is needed; no public-ID rotation workflow is offered |
| Activation token, act_ | One activated app installation; protected local storage | Never bundle a token for all customers | [License](/docs/v1/start/glossary#license)/[device](/docs/v1/start/glossary#device) binding; status-based acceptance, no independent elapsed-time TTL check; license and signed-cache deadlines still apply | Re-activate the installation; its prior active token is revoked |
| Developer API key, lmp_ | Your trusted backend secret configuration | No | [Organization](/docs/v1/start/glossary#organization), product, environment and scopes; configured expiry/revocation apply | Dashboard rotation immediately revokes the old key; no overlap window |

## Headers and environment
Activation sends X-App-ID and X-Environment: [SANDBOX](/docs/v1/start/glossary#sandbox) or LIVE. Its body contains the [license key](/docs/v1/start/glossary#license-key) and stable device_id. An optional email must match the license's customer.
Validation sends Authorization: Bearer followed by the activation token and X-Installation-ID containing the same persisted identity. Always send the installation header; the API currently accepts its omission, but then signs a null installation hash that conforming SDK checks do not accept.
Management sends Authorization: Bearer followed by the developer API key. That key, not an X-Environment override, determines the environment. Do not substitute an activation token into a management operation.

## Registered scopes
| Scope | Registered operations |
| --- | --- |
| licenses:read | Read a license by ID |
| licenses:write | Create, revoke, suspend, restore and renew licenses |
| devices:write | Reset devices for a license |
An arbitrary scope string does not create a new API permission. A reset-devices key does not gain license-creation rights.

## Create a key
1. Open API keys in the dashboard.
2. Choose the product and Sandbox or Live environment.
3. Select only the scopes your server needs.
4. Set a descriptive key name and any supported expiry.
5. Create the key and copy the full secret once into your server's secret configuration.
Expected result: the listing contains a display prefix, not a recoverable complete secret. Live issuance needs eligible paid access.
For client-only quickstart activation, do not create a management key at all.

## Rotate or revoke
1. Identify the intended key by its name, product and environment.
2. Use Rotate when replacing it, or Revoke when stopping all future use.
3. For rotation, copy the new secret and deploy it to the trusted backend.
4. Confirm a management request works with the replacement.
5. Review API and audit logs for unexpected failures.
Expected result: old-key requests fail. Rotation has no overlap; coordinate the backend update rather than assuming a zero-interruption grace window.

## Correct use by application
| App type | Correct | Incorrect |
| --- | --- | --- |
| Desktop | Public App ID and customer key activate; local token validates | Embed an lmp_ key in the executable |
| SaaS | Authenticate your user and gate server actions using valid license state | Trust a browser's paid=true claim |
| CLI | Persist identity and token in protected per-user state | Print a token into shell logs |
| Plugin or extension | Customer host uses activation credentials; your server manages licenses | Treat the customer's server or extension bundle as your secret vault |

## If a key leaks
1. Revoke the compromised key, or rotate it and securely deploy the replacement.
2. Review API and audit history for that key's product/environment and [request IDs](/docs/v1/start/glossary#request-id).
3. Identify affected licenses and investigate actual changes.
4. Suspend or revoke only licenses requiring that response under your policy.
5. Remove the exposed value from your release process and notify affected parties when appropriate.
Expected result: the old credential no longer works and the investigation is recorded. Deleting a public post alone does not invalidate a leaked key.

## Expected result
You can explain which secret is on the client, which is on the server, and how the selected environment is enforced.

## Common mistakes
- Treating the public App ID as a management secret.
- Rotating a [developer](/docs/v1/start/glossary#developer) key without updating its consumer.
- Omitting X-Installation-ID and accepting a signed response for no bound installation.
- Assuming a restored license revives its revoked activation tokens.

## Security notes
Developer and activation tokens are hashed in their corresponding database records. [Webhook](/docs/v1/start/glossary#webhook) secrets are a different credential, with an encrypted copy used for [delivery](/docs/v1/start/glossary#delivery). Do not put any of these secrets into documentation feedback.
A credential's successful authentication is not a promise that every resource-creation operation is allowed; endpoint scopes, current plan gates and license rules still apply.

## Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| INVALID_API_KEY | Missing, expired, revoked or ineligible developer credential | Check the server's current key and environment |
| INSUFFICIENT_SCOPE | Key lacks the operation's registered scope | Issue an appropriately scoped key; do not broaden a shipped client |
| INVALID_TOKEN | Installation token is missing, replaced or invalidated | Re-activate only an eligible license |
| DEVICE_MISMATCH | Installation header differs from the token's binding | Load the original persisted ID instead of generating one per request |

## Next steps
Run the [quickstart](/docs/v1/start/quickstart), then read the [activation flow](/docs/v1/start/activation-validation-deactivation).

## Related
- [Environments](/docs/v1/start/environments)
- [License lifecycle](/docs/v1/start/license-lifecycle)
- [Current integration limitations](/docs/v1/integration-notes)