Palm OpenAPI Server-Side Skill User Guide

1. Product Overview

palm-openapi is an AI Agent Skill for the Palm Open Platform server-side API. After installing it and completing tenant environment configuration, you can use natural language directly to have the AI assistant perform the following operations in your tenant:

Query resources: Query information such as users, devices, scenes, palm prints, and verification records
Manage resources: Create, modify, or delete resources such as users, devices, scenes, and verification rules
Manage palm prints: Create, bind, register, delete, and query palm prints, and perform Mobile Palm Registration Search and user additional verification
Use QR Code Palm Registration capabilities: Create QR Code Palm Registration sessions, notify scan events, bind palm prints, and query scan users and session status
Manage multiple tenant environments: Save connection information for multiple tenants locally, and specify the tenant environment to operate on when making calls
Query interface descriptions: List available APIs and view the required parameters, optional parameters, and usage notes of a specified Action

The Python CLI built into the Skill automatically handles signing, token acquisition, request sending, and result parsing.

2. Quick Start

For first-time use, complete the following steps in order:

Download and install the Skill
Confirm the palm-openapi Skill has taken effect
Prepare the tenant configuration information
Configure the tenant environment
Check the configuration result
Complete your first API call

2.1 Download and Install the Skill

Download palm-openapi.zip, then unzip it:

unzip palm-openapi.zip

Place the entire unzipped palm-openapi folder into the AI assistant's local Skills directory. The Skills directory may differ across AI assistants; refer to the installation instructions of the corresponding product:

cp -R palm-openapi <AI_ASSISTANT_SKILLS_DIR>/

The directory structure after installation is as follows:

<AI_ASSISTANT_SKILLS_DIR>/
└── palm-openapi/
    ├── README.md                       # User installation and operation manual
    ├── SKILL.md                        # AI Agent trigger rules and workflow
    ├── commands/
    │   └── palm-openapi.md             # Command definition
    ├── references/
    │   └── api_doc.md                  # Complete API documentation
    └── scripts/
        └── palm_openapi_cli.py         # Palm OpenAPI CLI script

You can use the following command to check whether the files are complete:

ls <AI_ASSISTANT_SKILLS_DIR>/palm-openapi

After confirming the directory is complete, reload or reopen the AI assistant so that it recognizes the newly installed Skill.

If you need to run the CLI manually, first enter the Skill root directory and check the Python dependencies:

cd <AI_ASSISTANT_SKILLS_DIR>/palm-openapi
python3 --version
python3 -c "import requests; print(requests.__version__)"

If it reports that requests is missing, you can install it in the current Python environment:

python3 -m pip install requests

2.2 Confirm the Skill Has Taken Effect

After installation, you can first ask the AI assistant:

Please use the palm-openapi Skill and tell me what you can help me with.

You can also directly describe the operation you want to perform:

Help me create a new user.

Help me query the information of user user001.

Help me query the details of device device-001.

Help me list all available Palm OpenAPI interfaces.

If the tenant environment has not been configured yet, the AI assistant will first guide you to prepare and configure the required information.

2.3 Prepare the Tenant Configuration Information

2.3.1 Information You Need to Provide

Parameter	Description	Required
Tenant environment name	A local configuration name you define, such as `test`, `tenant-a`, or `customer-prod`. Used only to distinguish different tenant environments; it does not modify tenant information. Defaults to `test` if not filled in	Optional
APP_ID	The tenant's application ID. Each tenant has only one unique `APP_ID`	Required
SECRET_ID	The secret ID of the service administrator credential. Credentials generated by different administrators may differ	Required
SECRET_KEY	The secret key paired with `SECRET_ID`. Credentials generated by different administrators may differ; keep it safe	Required
HOST	The Palm OpenAPI service domain of the current customer system, such as `openapi.customer.example.com`. Each customer system has only one `HOST` and it does not change with the tenant	Required

2.3.2 Where to Obtain APP_ID, SECRET_ID, and SECRET_KEY?

In the Tencent PalmAI Admin Console, navigate in sequence to:

System Management → Tenant Management → Tenant Details → Basic Information

In "Basic Information", view the following information for the corresponding tenant:

APP_ID: Corresponds to the current tenant; each tenant has only one unique value
SECRET_ID: The secret ID of the service administrator credential
SECRET_KEY: The secret key paired with SECRET_ID

The same tenant can have different credentials generated by different service administrators, so the SECRET_ID and SECRET_KEY obtained by different administrators may differ. When making calls, you must use a matching pair of SECRET_ID and SECRET_KEY.

2.3.3 Where to Obtain HOST?

Other administrators: Contact the super administrator or O&M personnel to obtain the Open Domain of the current customer system.
Super administrator: In the Tencent PalmAI Admin Console, navigate in sequence to:

System Management → System Settings → Service Endpoints → Open Domain

Open Domain corresponds to the HOST to be configured. Each customer system has only one domain, and it does not change with the tenant.

2.4 Configure the Tenant Environment

2.4.1 Have the AI Assistant Complete the Configuration

In a trusted local AI session, send the following information, replacing the example values with your real configuration:

Please use the palm-openapi Skill to configure the tenant environment:
Tenant environment name: tenant-a
APP_ID: your tenant application ID
SECRET_ID: your service administrator secret ID
SECRET_KEY: the secret key paired with SECRET_ID
HOST: openapi.customer.example.com

The AI assistant will call the built-in CLI to save and verify the tenant environment. The corresponding CLI command is as follows:

python3 scripts/palm_openapi_cli.py \
  --save-env tenant-a \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>" \
  --host <HOST>

The value after --save-env is the tenant environment name. The configuration is saved locally to ~/.palm_openapi.json, with file permission set to 600, readable and writable only by the current system user.

The credentials in ~/.palm_openapi.json are stored as local plaintext configuration, not encrypted. Use them only on trusted devices; do not upload, share, or commit them to a code repository.

2.4.2 Interactive Configuration in a Local Terminal

If you do not want to write the credentials directly in the command parameters, you can run the following in a local terminal:

python3 scripts/palm_openapi_cli.py --setup-env

Fill in the tenant environment name, HOST, APP_ID, SECRET_ID, and SECRET_KEY in sequence as prompted. This method relies on terminal interaction, is suitable for manual operation by users, and is not suitable for automatic execution by an AI Agent.

2.5 Check the Tenant Environment

After configuration, run the following command to view the configured tenant environments:

python3 scripts/palm_openapi_cli.py --list-envs

Confirm that the tenant environment name, HOST, APP_ID, and credential source in the output are as expected. The script does not display the full SECRET_KEY directly.

You can also have the AI assistant check directly:

Please use the palm-openapi Skill to list the tenant environments I have configured.

2.6 Complete Your First API Call

For the first time, it is recommended to run a read-only query first to confirm that the tenant environment and credentials work properly. For example:

Please use the tenant environment tenant-a to query the user list and return the first 10 records.

The corresponding CLI command is as follows:

python3 scripts/palm_openapi_cli.py DescribeUserList \
  '{"Offset": 0, "Limit": 10}' \
  --env tenant-a

If the interface returns data or an empty list normally, the Skill, tenant environment, and credentials have been configured successfully. If it returns an authentication or connection error, check the following in order:

Whether APP_ID belongs to the current tenant
Whether SECRET_ID and SECRET_KEY are a matching pair of credentials
Whether HOST is the Open Domain of the current customer system
Whether the current device can access the service domain
Whether the system time is accurate

3. Using Natural Language

After completing the initial configuration, simply describe the operation and related parameters in natural language. For example:

What can you help me with?

Help me query the information of user user001.

Help me create a new user with user ID test001, user name Test User, and phone number (+86)13800138000.

Help me query the details of device device-001.

What are the required and optional parameters of the CreateUser interface?

Help me list all available Palm OpenAPI interfaces.

The test tenant environment is used by default. Only when multiple tenant environments are configured or you need to switch tenants do you need to state it explicitly:

Please use the tenant-a tenant environment to query the information of user user001.

The AI assistant will automatically:

Match the natural language requirement to the corresponding API Action
Query the required and optional parameters of the interface
Ask you when necessary information is missing
Use the current tenant environment to obtain the Token and complete signing
Call the API and parse the returned result or error information

For operations that change tenant data, such as create, modify, delete, and bind, confirm the tenant environment and parameters before execution to avoid operating on the wrong tenant.

4. Using the CLI

You can also use the Python CLI built into the Skill directly.

4.1 Basic Call

# Use the default tenant environment test
python3 scripts/palm_openapi_cli.py <Action> '<JSON parameters>'

# Use a specified tenant environment
python3 scripts/palm_openapi_cli.py <Action> '<JSON parameters>' --env <tenant_env_name>

4.2 Call Examples

# Query a user
python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-a

# Create a user
python3 scripts/palm_openapi_cli.py CreateUser \
  '{"UserId": "test001", "UserName": "Test User", "PhoneNo": "(+86)13800138000"}' \
  --env tenant-a

# Query a device
python3 scripts/palm_openapi_cli.py DescribeDevice \
  '{"DeviceSn": "device-001"}' \
  --env tenant-a

4.3 Common Helper Commands

# List the Actions the CLI supports calling proactively
python3 scripts/palm_openapi_cli.py --list-actions

# View the parameter description of a specified Action
python3 scripts/palm_openapi_cli.py --help-action <Action>

# List configured tenant environments
python3 scripts/palm_openapi_cli.py --list-envs

# Interactively configure a tenant environment
python3 scripts/palm_openapi_cli.py --setup-env

# Non-interactively save a tenant environment
python3 scripts/palm_openapi_cli.py \
  --save-env <tenant_env_name> \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>" \
  --host <HOST>

# View the full CLI help
python3 scripts/palm_openapi_cli.py --help

4.4 Switch Tenant Environments

Specify the tenant environment name via --env on each call:

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-a

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-b

The tenant environment name is merely a local configuration identifier. Switching --env does not modify any tenant information; it only determines which set of APP_ID, SECRET_ID, SECRET_KEY, and HOST is used for this call.

4.5 Temporarily Specify Tenant Connection Information

If you do not need to save the configuration, you can pass in the complete information in a single call:

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --host openapi.customer.example.com \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>"

Command-line parameters may be recorded by the terminal history or the local process list. Use them only on trusted local devices; do not paste commands containing real credentials into tickets, documentation, group chats, or public logs.

5. Tenant Environment Configuration

5.1 Configuration Save Location

Default configuration file:

~/.palm_openapi.json

The script sets the file permission to 600. You can also specify another configuration file in the following ways:

# Specify the configuration file via the command line
python3 scripts/palm_openapi_cli.py \
  --config /path/to/palm_openapi.json \
  DescribeUser '{"UserId": "user001"}' \
  --env tenant-a

# Specify the configuration file via an environment variable
export PALM_CONFIG_FILE=/path/to/palm_openapi.json

5.2 Configuration Reading Priority

The tenant environment configuration is read according to the following priority, where higher priority overrides lower priority:

Command-line parameters: --secret-id, --secret-key, --app-id, --host
Environment variables: PALM_{tenant_env_name}_{KEY}
Configuration file: --config, PALM_CONFIG_FILE, or ~/.palm_openapi.json

For example, when the tenant environment name is tenant-a, the hyphen in the environment variable name needs to be adjusted according to the variable naming convention supported by the current terminal. It is recommended to use letters, digits, and underscores for the tenant environment name, such as tenant_a:

export PALM_TENANT_A_APP_ID="<APP_ID>"
export PALM_TENANT_A_SECRET_ID="<SECRET_ID>"
export PALM_TENANT_A_SECRET_KEY="<SECRET_KEY>"
export PALM_TENANT_A_HOST="openapi.customer.example.com"

python3 scripts/palm_openapi_cli.py DescribeUserList \
  '{"Offset": 0, "Limit": 10}' \
  --env tenant_a

6. Image Interfaces

Interfaces involving palm print images must pass in the image via a file path, which the script reads and base64-encodes. Do not read the image manually, and do not write the base64 image data directly into the JSON parameters.

# Create palm print
python3 scripts/palm_openapi_cli.py CreatePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --ir-image ./ir.jpg \
  --env tenant-a

# Register palm print
python3 scripts/palm_openapi_cli.py RegisterPalm \
  '{"UserId": "user001", "PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --ir-image ./ir.jpg \
  --env tenant-a

# Mobile Palm Registration Search
python3 scripts/palm_openapi_cli.py SearchMobilePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --env tenant-a

To pass in image three-point data:

python3 scripts/palm_openapi_cli.py CreatePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --rgb-three-points "365.29,193.33,285.36,196.08,212.50,241.93" \
  --ir-image ./ir.jpg \
  --ir-three-points ./threepoints.txt \
  --env tenant-a

7. Supported API Capabilities

Module	Capabilities
Authentication Management	Automatically obtain access credentials, query authorization information
Palm Print Management	Create, bind, register, delete, and query palm prints; Mobile Palm Registration Search, user additional verification, synchronize palm print features, query product versions
User Management	Create, modify, delete, and query users; query the user list
User Tags	Create, modify, delete, and query user tags; query the tag list and tag tree
User Palms	Delete and query user palm information; query user access scope and summary
Device Management	Create, modify, delete, and query devices; query the device list
Scene Management	Create, modify, delete, and query scenes and scene groups
Verification Records	Create and query verification records
Verification Rules	Create, modify, delete, and query verification rules
QR Code Palm Registration	Create and query QR Code Palm Registration sessions, notify scan events, bind palm prints, query scan users
PalmMa Login	Send SMS verification codes, log in with an SMS verification code

Features are continuously updated; the actual features are subject to the latest version of the Skill. After installation, you can use natural language to ask the AI assistant directly:

What features does this Skill support?

What operations does palm print management support?

You can also view the complete Action list via the CLI:

python3 scripts/palm_openapi_cli.py --list-actions

View the parameters of a specified interface:

python3 scripts/palm_openapi_cli.py --help-action <Action>

8. Notes

Confirm the tenant environment: Before performing create, modify, delete, or bind operations, you must confirm that --env points to the correct tenant environment.
Protect credentials: Do not expose the real SECRET_ID, SECRET_KEY, or AccessToken in public chats, screenshots, logs, documentation, or code repositories.
HOST must be accurate: Basic administrators should obtain it from the super administrator or O&M personnel; the super administrator should view it under "System Management → System Settings → Service Endpoints → Open Domain".
Do not obtain the Token manually: The script automatically calls CreateAccessToken; there is no need to manually compute SecretKeyHash or maintain the Token.
ModifyUser is a full update: Optional fields not passed in may be cleared. Query and confirm the fields you need to retain before calling.
Use file paths for images: Image interfaces such as CreatePalm, RegisterPalm, and SearchMobilePalm should use --rgb-image and --ir-image.
Push and callback interfaces cannot be pulled proactively: DescribeVerificationRecord and CheckAccessPermission are called by the platform.
Do not disable TLS verification arbitrarily: Production tenant environments should use trusted service domains and valid certificates.

1. Product Overview​

2. Quick Start​

2.1 Download and Install the Skill​

2.2 Confirm the Skill Has Taken Effect​

2.3 Prepare the Tenant Configuration Information​

2.3.1 Information You Need to Provide​

2.3.2 Where to Obtain APP_ID, SECRET_ID, and SECRET_KEY?​

2.3.3 Where to Obtain HOST?​

2.4 Configure the Tenant Environment​

2.4.1 Have the AI Assistant Complete the Configuration​

2.4.2 Interactive Configuration in a Local Terminal​

2.5 Check the Tenant Environment​

2.6 Complete Your First API Call​

3. Using Natural Language​

4. Using the CLI​

4.1 Basic Call​

4.2 Call Examples​

4.3 Common Helper Commands​

4.4 Switch Tenant Environments​

4.5 Temporarily Specify Tenant Connection Information​

5. Tenant Environment Configuration​

5.1 Configuration Save Location​

5.2 Configuration Reading Priority​

6. Image Interfaces​

7. Supported API Capabilities​

8. Notes​