Brazil Receita WS Authentication: Methods & Best Practices (2026)

Authentication overview

Accessing services provided by the Brazil Receita WS, the Brazilian Federal Revenue Service, requires robust authentication mechanisms to protect sensitive taxpayer data. The primary methods ensure that only authorized individuals or entities can query information related to CNPJ (National Registry of Legal Entities) and CPF (Individual Taxpayer Registry) or submit fiscal declarations. These methods are aligned with Brazilian digital government initiatives, emphasizing security, non-repudiation, and legal compliance for digital interactions with public services. The choice of authentication method often depends on the specific Receita Federal service being accessed and the nature of the user (individual or legal entity).

The Brazilian Public Key Infrastructure (ICP-Brasil) forms the foundation for digital certificate-based authentication, providing a legal framework for electronic signatures and secure digital identities. This infrastructure ensures the authenticity, integrity, and validity of electronic documents and transactions, making it a cornerstone for secure interactions with government systems. For individuals, the Gov.br platform has become a centralized identity provider, simplifying access to various federal services through a single login, often backed by multi-factor authentication (MFA) to enhance security.

Supported authentication methods

Brazil Receita WS supports several authentication methods, each designed for specific use cases and security requirements. The two predominant methods are digital certificates and the Gov.br account. Understanding when to use each method and their respective security levels is crucial for developers integrating with Receita Federal services.

Digital Certificates (e-CPF and e-CNPJ)

Digital certificates, specifically e-CPF for individuals and e-CNPJ for legal entities, are X.509 certificates issued by Certification Authorities accredited by ICP-Brasil. These certificates serve as digital identities, allowing users to sign documents electronically with legal validity and access restricted government services. They are typically stored on smart cards, USB tokens, or in the cloud. The use of digital certificates provides a high level of security due to their reliance on public-key cryptography and the stringent identity verification processes required for their issuance, as detailed by the ICP-Brasil framework.

Gov.br Account

The Gov.br account is a unified access system for federal public services in Brazil. It offers different levels of reliability (Bronze, Silver, Gold), determined by the methods used to verify the user's identity. A Gold-level Gov.br account, for instance, requires robust identity verification, often involving facial recognition or digital certificate linkage, offering a higher degree of assurance for sensitive transactions. This method often integrates with OAuth 2.0 or OpenID Connect for delegated authorization, allowing applications to access user data with consent. More information on Gov.br account levels can be found on the Gov.br portal.

Authentication Methods Comparison

Getting your credentials

Obtaining the necessary credentials for Brazil Receita WS authentication involves specific steps for each method:

For Digital Certificates (e-CPF/e-CNPJ)

1. Choose a Certification Authority (CA): Select an accredited CA from the list provided by ICP-Brasil. Examples include Serpro, Certisign, or Caixa.
2. Request the Certificate: Initiate the request process through the chosen CA's website. This typically involves filling out a form with personal or company details.
3. Identity Verification: Attend an in-person or video conference validation session. For e-CNPJ, company documents and legal representatives must be verified. For e-CPF, personal documents are required.
4. Issuance and Installation: Once verified, the CA issues the certificate. You will receive instructions on how to install it on a smart card, USB token, or in a cloud environment.

For Gov.br Account

1. Create an Account: Visit the Gov.br portal and register for an account using your CPF.
2. Increase Reliability Level: To access more sensitive Receita Federal services, you need to upgrade your account to Silver or Gold.
• Silver Level: Can be achieved through online banking validation (from specific banks), or by validating data via the National Driver's License (CNH) or Biometric Justice Electoral.
• Gold Level: Requires facial recognition through the Meu Gov.br app (matching with CNH data), or validation via a digital certificate (e-CPF).

Authenticated request example

While direct API access details for all Brazil Receita WS services are often specific to each service and require adherence to their particular documentation, a common pattern for services requiring digital certificates involves signing the request payload. For services integrated with Gov.br, OAuth 2.0 is frequently used.

Example with Digital Certificate (Conceptual)

When using a digital certificate, the typical process involves signing the request data (e.g., an XML or JSON payload) with the private key associated with your e-CPF or e-CNPJ. The public key is then used by the Receita Federal system to verify the signature's authenticity and integrity. This process often leverages libraries that interact with the local certificate store or a hardware security module (HSM).

<?xml version="1.0" encoding="UTF-8"?>
<RequestData xmlns="http://example.com/receita-ws/v1">
  <CNPJ>12345678000190</CNPJ>
  <QueryType>CadastroEmpresa</QueryType>
  <Timestamp>2026-05-29T10:00:00Z</Timestamp>
  <SignatureValue>[Base64 encoded digital signature of the above data]</SignatureValue>
  <X509Certificate>[Base64 encoded public certificate]</X509Certificate>
</RequestData>

The actual implementation would involve cryptographic operations using a programming language's security libraries (e.g., Java's KeyStore API, .NET's X509Certificate2 class, or Python's cryptography library) to load the certificate, sign the data, and embed the signature and certificate into the request. The specific XML or JSON structure would be defined by the particular Receita Federal service's WSDL or API specification.

Example with Gov.br Account (Conceptual OAuth 2.0)

For services leveraging Gov.br, the flow typically follows the OAuth 2.0 Authorization Code Grant type. Your application redirects the user to Gov.br for authentication, receives an authorization code, and then exchanges it for an access token.

# Step 1: User is redirected to Gov.br for authorization
GET https://sso.acesso.gov.br/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid%20profile%20email&state=STATE_VALUE

# Step 2: Gov.br redirects back to your application with an authorization code
GET YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE_VALUE

# Step 3: Your application exchanges the code for an access token
POST https://sso.acesso.gov.br/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

# Response (conceptual)
{
  "access_token": "ACCESS_TOKEN_VALUE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

# Step 4: Use the access token to call a protected API endpoint
GET https://api.receita.gov.br/v1/protected-resource
Authorization: Bearer ACCESS_TOKEN_VALUE

This example illustrates the general OAuth 2.0 flow. Specific endpoints, scopes, and parameters would be provided in the official documentation for the particular Receita Federal service being integrated.

Security best practices

Adhering to security best practices is paramount when interacting with Brazil Receita WS to protect sensitive fiscal data and maintain compliance.

• Secure Credential Storage: Never hardcode digital certificate passwords or Gov.br client secrets directly in your application code. Use secure environment variables, secret management services (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager), or hardware security modules (HSMs) for storing private keys and sensitive credentials. The AWS Secrets Manager documentation provides guidance on secure secret storage.
• Least Privilege Principle: Grant only the minimum necessary permissions to your application or user account. For digital certificates, ensure they are used only for their intended purpose. For Gov.br accounts, ensure the associated application only requests the necessary OAuth scopes.
• Regular Credential Rotation: Periodically rotate API keys, client secrets, and renew digital certificates before their expiration to minimize the window of opportunity for compromised credentials.
• Input Validation and Sanitization: Always validate and sanitize any input received from users or external systems before processing it or passing it to Receita Federal APIs. This helps prevent injection attacks and ensures data integrity.
• Error Handling and Logging: Implement robust error handling that avoids exposing sensitive information in error messages. Log authentication attempts and failures, but ensure logs do not contain sensitive credentials. Regularly review logs for suspicious activity.
• Transport Layer Security (TLS): Always use HTTPS for all communications with Receita Federal endpoints. This ensures that data exchanged between your application and the government services is encrypted in transit, preventing eavesdropping and tampering.
• Multi-Factor Authentication (MFA): When possible, enable and enforce MFA for all accounts accessing Receita Federal services, especially for Gov.br accounts, to add an extra layer of security beyond just a password.
• Keep Dependencies Updated: Regularly update all libraries, frameworks, and operating systems used in your application to patch known security vulnerabilities.
• Compliance with LGPD: Ensure your application's data handling practices comply with Brazil's Lei Geral de Proteção de Dados Pessoais (LGPD), particularly concerning the collection, storage, and processing of personal data obtained from Receita Federal services.