API authentication

Use this guide to get your API keys, understand environments, and authenticate every request to the Envia APIs.

1. Create your account

You need separate accounts for sandbox and production:

💡

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

2. Get your API key

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

Once logged in, navigate to Desarrolladores → Acceso de API in the left sidebar. On this page you can:

1. 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.
2. Create a new token — Click Agregar in the top-right corner to generate a new API key.

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

⚠️

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. Environments and base URLs

The Shipping and Queries APIs have separate sandbox and production URLs. The Geocodes API only has a production endpoint — use it in both environments:

Sandbox returns simulated responses and is safe for testing. Production creates real labels and charges your account balance. Use separate webhook URLs per environment to avoid mixing event data.

5. 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"

Troubleshooting

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

• Shipping API: Returns plain text "Authentication error." with HTTP 401.
• Queries & Geocodes APIs: Return JSON {"statusCode": 401, "error": "Unauthorized", "message": "..."}.

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?