API Token

1. Create your account

💡

Recommendation

Start with a sandbox account. You can test every API feature without affecting real shipments or incurring charges.

2. Get your API Token

Each environment has its own dashboard. Log in to the one you want to use:

Once logged in, navigate to Developer → API Keys in the left sidebar. On this page you can:

1. Create a new token: Click Add in the top-right corner to generate a new API key.
2. Copy an existing token: Click the copy icon next to the token to copy it to your clipboard. Use the eye icon to reveal the full value.

Use the Delete button next to a token to revoke it when it is no longer needed.

⚠️

Important Note

Each key works only in the environment where it was created. A sandbox key cannot authenticate production requests, and vice versa.

3. Store your key securely

Set the token as an environment variable so it stays out of your source code:

# Sandbox
export ENVIA_TOKEN="your-sandbox-token-here"

# Production (when ready to go live)
# export ENVIA_TOKEN="your-production-token-here"

Best practices for key management:

• Keep sandbox and production keys in separate secret stores or .env files
• Never commit API keys to version control
• Rotate keys on a regular schedule
• Revoke unused or old keys immediately

4. Authenticate your requests

All Envia APIs use Bearer Token authentication. Include your token in the Authorization header of every request:

curl --request GET \
  --url https://queries-test.envia.com/webhook-types \
  --header "Authorization: Bearer $ENVIA_TOKEN"

const response = await fetch("https://queries-test.envia.com/webhook-types", {
  headers: {
    Authorization: `Bearer ${process.env.ENVIA_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://queries-test.envia.com/webhook-types",
    headers={"Authorization": f"Bearer {os.environ['ENVIA_TOKEN']}"},
)
data = response.json()

Troubleshooting

If authentication fails, the response depends on which API you are calling:

• Shipping API: Returns plain text "Authentication error." with HTTP 401.
• Queries API: Returns JSON {"statusCode": 401, "error": "Unauthorized", "message": "..."}. (The Geocodes API does not require authentication, so 401 is not applicable.)

Common causes:

• The Authorization header is missing or misspelled
• The token is expired or was revoked
• You are using a sandbox token against a production URL (or vice versa)

Fix: Confirm the token and the base URL match the same environment. Sandbox tokens only work with -test URLs. See Error Response Formats for the full error shapes returned by each API.

What's next?