Secret Handling Requirements

This page covers one thing only: how to store and use the two most sensitive secrets in a TiRTC integration, and what you must not do with them.

If you have already read the Glossary, the key point can be summarized like this:

• secret_key is the application-level secret
• device_secret_key is the device-level secret
• both values are sensitive and must not be leaked

Which secrets need special protection

secret_key

secret_key is the application-level secret.

It is usually held by your backend service and used for signing and authentication.

device_secret_key

device_secret_key is the device-level secret.

Together with device_id, it describes the identity of one device and may also be used in device-related signing or verification.

Where these secrets should be stored

Store secret_key on the server side only

secret_key must not appear in any of the following places:

• client application source code
• client app packages
• frontend page scripts
• debug screenshots, chat logs, or support tickets

If a client app can read secret_key directly, your trust boundary is already wrong.

Store device_secret_key only in controlled device-side or server-side locations

device_secret_key must not be treated like ordinary configuration.

It should only appear where it is truly required, for example:

• a controlled storage location used during device initialization or device onboarding
• a controlled storage location used by the backend for signing or verification

Outside those necessary cases, other code, tools, or troubleshooting flows should not have direct access to it.

What you must not do

The following are high-risk misuse patterns:

• putting secret_key into client code or sample projects
• logging device_secret_key as plain text
• sending full secrets in chats, emails, tickets, or screenshots
• treating license as a harmless string that can be shared freely
• storing secrets in local config files and committing them to the repository

Pay special attention to the last point.

In the docs, license is often described as a combination of device_id + device_secret_key, but that does not mean it is safe to circulate as one complete value.

Recommended practices

Log identifiers only, never secrets

If you need to troubleshoot device issues, log things like:

• device_id
• remote_id
• connection state
• error codes

Do not log:

• secret_key
• device_secret_key
• the full license
• a reusable full token

Mask sensitive fields during troubleshooting

If a related field must be displayed, show only the smallest amount of information needed for diagnosis.

For example:

• show only the first few and last few characters
• show device_id without device_secret_key
• report "signature verification failed" or "credential mismatch" instead of dumping the original secret

Split access by responsibility

Each side should only access the information it truly needs:

• clients mainly use remote_id and token
• devices only access device_secret_key when required
• backend services access secret_key and device_secret_key only when required

Do not pass every sensitive field to every side just because it is convenient.

What to do if a secret is leaked

If you suspect secret_key or device_secret_key has already leaked, prioritize these actions:

1. Stop further sharing immediately.
2. Confirm the leak scope: code repositories, logs, chats, screenshots, and tickets.
3. Rotate or reissue the affected secret according to your internal process.
4. Revoke or clean up historical leaked copies.
5. Check whether your docs, samples, or troubleshooting scripts still expose the field.

Related pages

• Glossary
• Connection