Correios Authentication: API Access and Security (2026)

Authentication overview

Correios, Brazil's national postal service, provides programmatic access to its services primarily through the SIGEP Web and WSPro APIs. These interfaces facilitate functions such as calculating shipping costs, tracking parcels, and managing postal orders for commercial partners. Authentication for these APIs is based on a traditional username and password model, requiring prior registration and a commercial agreement with Correios. This approach ensures that API access is restricted to legitimate business entities that have established a formal relationship with the postal service.

The authentication process typically involves including these credentials within the SOAP header of each API request. This method, while straightforward, necessitates careful handling of credentials to prevent unauthorized access. Developers integrating with Correios APIs should prioritize secure storage and transmission of these credentials, adhering to industry best practices for API key management and secret protection. The official Correios WSPro documentation provides detailed instructions on how to structure authenticated requests and manage access for various services, outlining the specific parameters required for each operation.

Supported authentication methods

Correios primarily supports a credential-based authentication method for its SIGEP Web and WSPro SOAP APIs. This method relies on a unique username and password pair issued to authorized commercial partners after establishing a contract with Correios. There are no direct provisions for token-based authentication methods like OAuth 2.0 or API keys as standalone headers in the same manner as many RESTful APIs.

The authentication details, specifically the usuario (username) and senha (password), are typically embedded within the SOAP envelope's header for each request. This means that every call to a protected Correios API endpoint must carry these credentials. While this method is effective for access control, it places a significant responsibility on the integrating application to secure these credentials at rest and in transit.

For enhanced security, all communication with Correios API endpoints is expected to occur over HTTPS, ensuring that the username and password are encrypted during transmission via Transport Layer Security (TLS). This prevents eavesdropping and tampering of credentials as they travel over the network. Developers should verify that their API client is configured to enforce TLS 1.2 or higher for all Correios API interactions.

The table below summarizes the primary authentication method:

While this method is the standard for Correios, modern API security often favors token-based approaches for their stateless nature and ability to grant fine-grained permissions without transmitting static credentials repeatedly. For example, OAuth 2.0 provides a framework for delegated authorization, allowing third-party applications to access resources on behalf of a user without exposing their credentials directly, as detailed in the OAuth 2.0 specification. However, Correios's current API architecture does not natively support such protocols.

Getting your credentials

Accessing the Correios WSPro and SIGEP Web APIs requires a formal registration process and the establishment of a commercial contract with Correios. Unlike many public APIs that offer self-service sign-up for API keys, Correios's system is designed for business-to-business (B2B) integrations.

1. Establish a Commercial Agreement: The first step is to contact Correios directly to discuss your business needs and establish a commercial contract. This typically involves defining the scope of services you intend to use (e.g., specific shipping services, tracking volumes). Information on contacting Correios for commercial services can be found on their WSPro page.
2. Registration for API Access: Once a commercial agreement is in place, Correios will guide you through the process of registering for API access. This involves providing necessary business documentation and technical contact information.
3. Credential Issuance: Upon successful registration and approval, Correios will issue your unique API username (usuario) and password (senha). These credentials are specific to your commercial account and are essential for all authenticated API requests. Keep these credentials confidential and secure.
4. Sandbox/Homologation Environment: Correios typically provides access to a sandbox or homologation environment (ambiente de homologação) where you can test your integration without affecting live production systems. Your credentials might differ between the test and production environments. It is crucial to thoroughly test your integration in the homologation environment before deploying to production.

It is important to note that the entire process, including documentation and communication, is primarily conducted in Portuguese. Non-Portuguese speakers may need translation assistance to navigate the registration and integration steps effectively, as highlighted in the Correios WSPro developer experience notes.

Authenticated request example

For Correios WSPro, an authenticated request involves embedding the username and password within the SOAP header of your XML payload. Below is a conceptual example for a hypothetical service call, illustrating where these credentials would typically reside. This example assumes a SOAP client is being used to construct and send the request.

Example SOAP Request Structure (Conceptual):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.correios.com.br/">
   <soapenv:Header>
      <ser:credentials>
         <ser:usuario>YOUR_CORREIOS_USERNAME</ser:usuario>
         <ser:senha>YOUR_CORREIOS_PASSWORD</ser:senha>
      </ser:credentials>
   </soapenv:Header>
   <soapenv:Body>
      <ser:someServiceOperation>
         <!-- Service-specific parameters go here -->
         <ser:param1>value1</ser:param1>
         <ser:param2>value2</ser:param2>
      </ser:someServiceOperation>
   </soapenv:Body>
</soapenv:Envelope>

Explanation:

• <soapenv:Envelope>: The root element for all SOAP messages.
• <soapenv:Header>: This section is used for application-specific information that is not part of the message content itself, such as authentication credentials.
• <ser:credentials>: A hypothetical element within the header to encapsulate the authentication details. The actual element names (e.g., credentials, usuario, senha) will be defined by the specific WSDL (Web Services Description Language) provided by Correios for the service you are consuming.
• <ser:usuario>: Placeholder for your Correios-issued username.
• <ser:senha>: Placeholder for your Correios-issued password.
• <soapenv:Body>: Contains the actual message payload, including the parameters for the specific API operation you are invoking (e.g., someServiceOperation).

When implementing this, replace YOUR_CORREIOS_USERNAME and YOUR_CORREIOS_PASSWORD with your actual credentials. Always ensure that the communication is over HTTPS to protect these credentials during transit. Refer to the specific WSDL and operational documentation provided by Correios for the exact XML structure required for each service endpoint, as namespaces and element names can vary.

Security best practices

Securing your integration with Correios APIs is critical to protect your account and data. Given that Correios uses a username and password model embedded in SOAP headers, specific precautions are necessary.

1. Use HTTPS/TLS for All Communications: Always ensure that all API requests to Correios endpoints are made over HTTPS (HTTP Secure). This encrypts the data in transit, including your username and password, protecting them from interception. Verify that your client library or HTTP request mechanism enforces TLS 1.2 or higher. The Mozilla Developer Network's guide to TLS provides comprehensive information on its importance.
2. Secure Credential Storage: Never hardcode your Correios username and password directly into your application's source code. Instead, store them in secure environment variables, a secrets management service (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager), or a configuration management system that is access-controlled. This prevents credentials from being exposed in version control systems or publicly accessible code.
3. Principle of Least Privilege: If Correios offers different credential sets or roles, use the least privileged credentials necessary for your application's specific tasks. This minimizes the potential damage if credentials are compromised.
4. Regular Credential Rotation: Periodically change your Correios API password. While Correios might not enforce frequent rotations, it's a good security practice to reduce the window of opportunity for compromised credentials to be exploited.
5. Error Handling and Logging: Implement robust error handling without exposing sensitive information like credentials in logs. Log API request and response details for debugging and auditing, but redact or mask any authentication credentials. Ensure your logging infrastructure is secure and access-controlled.
6. IP Whitelisting (if available): If Correios provides an option to whitelist IP addresses from which API calls can originate, enable this feature. This restricts API access to only your trusted servers, adding an extra layer of security against unauthorized access attempts from unknown locations.
7. Monitor API Usage: Regularly monitor your API usage logs for any unusual activity or spikes in requests that could indicate unauthorized access or misuse.
8. Stay Updated: Keep your application's dependencies and libraries updated to patch any known security vulnerabilities. This includes the SOAP client library you use to interact with Correios APIs.
9. Isolate Production Credentials: Use separate credentials for development, testing (homologation), and production environments. Never use production credentials in non-production environments.

By diligently applying these security practices, developers can significantly reduce the risk of credential compromise and ensure a more secure integration with Correios APIs. Adhering to these guidelines aligns with general API security best practices recommended by industry leaders.