> This page is for version V3 - Beta (default).
> For other versions, use one of these documentation indexes:
> - V3 - Beta (default): https://docs.authlyx.dev/v3/llms.txt
> - V2 - Legacy: https://docs.authlyx.dev/v2/llms.txt
> - V1 - End of support: https://docs.authlyx.dev/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.authlyx.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.authlyx.dev/_mcp/server.

# Features and metadata

> Set plan permissions and keep details on each customer identity.

Features describe what a customer may use, or a product setting tied to their access. Metadata stores additional information about a plan, license, user or device. Both are named fields, but they serve different purposes.

## Start with two customer plans

MyApp is a video editor. Standard customers can preview HD video and export 10 files. Professional customers get 4K previews, PDF export and 100 exports. One Professional customer has a temporary agreement for 200 exports.

| Field                            | Standard plan     | Professional plan     | One Professional customer's override |
| -------------------------------- | ----------------- | --------------------- | ------------------------------------ |
| `exportPdf` - Bool               | false             | true                  | Uses plan default                    |
| `videoQuality` - String          | HD                | 4K                    | Uses plan default                    |
| `dailyExports` - Integer         | 10                | 100                   | 200 until the agreed date            |
| `helpUrl` - public metadata      | Standard help URL | Professional help URL | Uses plan default                    |
| `supportCase` - private metadata | Not set           | Not set               | AX-4812                              |

A number such as `dailyExports = 100` does not automatically count exports. Your app or trusted backend must enforce the operation and maintain any usage counter it needs.

## How AuthlyX chooses the value

```mermaid
flowchart TD
    A[Customer signs in to MyApp] --> B[Find their assigned customer plan]
    B --> C{Standard or Professional?}
    C -->|Standard| S[Defaults: HD, 10 exports, PDF disabled]
    C -->|Professional| P[Defaults: 4K, 100 exports, PDF enabled]
    S --> O[Read overrides on this license, user or device]
    P --> O
    O --> Q{Does this field have an unexpired identity override?}
    Q -->|Yes| V[Use the identity value, such as 200 exports]
    Q -->|No| W[Use the plan default, such as 100 exports]
    V --> R[Return the effective value to MyApp]
    W --> R
    R --> UI[MyApp uses the value for its interface and protected operations]
    O --> M[Resolve metadata visibility separately]
    M --> PUB[App-readable fields can reach the customer app]
    M --> PRIV[Private fields stay in authorized management tools]
```

## Create and edit features

Open the customer plan, then Features. Add a name and choose Bool, String or Integer. For example, add `videoQuality` as String. If you want fixed choices, provide allowed values such as HD, 2K and 4K. Its default must be one of those choices.

Edit an identity only when that customer needs a different value. Choose an existing feature and set the override. If Professional's default later changes, an unexpired customer override still takes priority. Customers without overrides use the current default.

An expiry belongs to the feature value or override you configure. It does not delete the customer's license. After an override expires, its plan default is used if available; if no valid value remains, the feature is absent. Define the fallback you want and handle missing fields in your app.

## Store additional information with metadata

`helpUrl` lets MyApp open the right support page. `supportCase` can help your staff find a private investigation. Metadata can be String, Integer or Bool, but it is not automatically an entitlement simply because its value is true.

Mark a field app-readable only if the customer software may see it. Anyone inspecting that software may see delivered data. Keep secrets and internal notes private. Metadata does not use a feature's allowed-values list and does not have feature expiry rules.

## Remote reads and updates

Use the SDK or Client API to read effective features and app-readable metadata for the current identity. Bool checks return whether the named Bool value is true. String and Integer values should be read as values, not treated as Boolean permission checks.

A metadata field may allow remote updates. The field must already exist, be app-readable and have remote writing enabled. The caller cannot use that permission to create arbitrary keys or edit another identity. Treat anything writable by customer software as untrusted input.

Client sessions cannot remotely edit feature entitlements. Use the authorized management API on a trusted server when your own service needs to update a customer's features.

Features require Plus or Elite; metadata requires Elite. A client-side feature check can be bypassed in a modified program. Enforce valuable server operations on your own trusted backend too.