Security settings

TronGrid provides several API key security settings to control where a key can be used, which APIs it can access, and whether requests require an additional signed token. Production systems should not rely on the API key alone. Configure allowlists or JWT based on your application model.

📘

Note

The security settings described on this page mainly apply to HTTP requests. Whether gRPC or other access methods support the same policies depends on the current TronGrid console and service behavior.

Security settings overview

User-Agent allowlist

The User-Agent allowlist restricts the client identifier that can use an API key. After configuration, only requests whose User-Agent header matches the allowlist can use that key.

Matching is usually substring-based. For example, configure:

com.example.wallet

A request header containing that string matches:

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'User-Agent: com.example.wallet/1.2.0 (Android)'

User-Agent can be spoofed, so it is useful as a basic filter but should not be the only security boundary. For high-value backend requests, combine it with request API allowlist, contract address allowlist, or JWT.

Origin allowlist

The Origin allowlist restricts browser request origins. It is suitable for Web DApps or admin dashboards and helps prevent other websites from reusing your API key.

For example, if your DApp is deployed at:

https://app.example.com

Add that Origin to the allowlist. After configuration, browser requests without a matching Origin header are rejected.

Origin matching rules

Origin rules can include a scheme such as https://. If the rule includes a scheme, the request must use the same scheme.

A wildcard can appear only in the leftmost subdomain and matches exactly one subdomain level. For example:

https://*.example.com

Matching results:

Request example:

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'Origin: https://app.example.com'

Contract address allowlist

The contract address allowlist restricts an API key to specified contract addresses. It is suitable for backends that serve only fixed Tokens, fixed DApp contracts, or fixed business contracts.

For example, allow only a specific TRC-20 contract:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

After the allowlist takes effect, compatible endpoints that contain contract address parameters reject requests that pass other addresses.

Request example:

curl --request GET \
  --url 'https://api.trongrid.io/v1/contracts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/events' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>'

Request API allowlist

The request API allowlist restricts an API key to specified methods. It is suitable for services with narrow responsibilities, such as reading account transaction history only, querying events only, or calling one standard node proxy endpoint.

If the allowlist is not empty, methods not listed are rejected. Configure production keys with least privilege: expose only the APIs that the service actually needs.

Example configuration:

GET /v1/accounts/{address}/transactions
GET /v1/contracts/{address}/events
POST /walletsolidity/gettransactionbyid

The exact method names and formats available for configuration depend on the TronGrid console.

JWT

JWT adds signed authentication on top of an API key. After JWT is enabled, each request must include both TRON-PRO-API-KEY and a valid Bearer token in the Authorization header.

TronGrid currently uses RS256 signatures. Generate an RSA key pair, configure the public key in the TronGrid console, and sign JWTs with the private key on your server.

Generate an RSA key pair

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Protect private.pem. The private key should be stored only in a controlled backend or key management system. Do not put it in frontend code, mobile apps, public repositories, or logs.

JWT Header and Payload

Header example:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<jwt-key-id>"
}

Payload example:

{
  "aud": "trongrid.io",
  "exp": 1893456000
}

Field meanings:

Use JWT with TronGrid

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'Authorization: Bearer <jwt-token>'

There must be one space between Bearer and the token. Requests are rejected when the JWT is expired, the signature is invalid, kid does not match, or aud is incorrect.

Recommended configurations

Related resources

• API Key — create keys, choose network endpoints, and configure request headers
• Rate limits — quota, rate-limit responses, and backoff strategies
• TronGrid V1 API overview — V1 API categories and typical use cases