Authentication overview

API Grátis employs API key authentication to secure access to its services, which provide real-time lookups and data for Brazilian entities such as CPF, CNPJ, and CEP. This method relies on a unique, secret key provided by API Grátis, which must be included with every API request to verify the client's identity and authorize the operation. This approach is common for public APIs where the primary concern is identifying the calling application and managing its usage limits.

The API key acts as a token that grants the holder permission to interact with the API endpoints. It is crucial for developers to protect these keys to prevent unauthorized access to their API Grátis account and potential misuse of their allocated request quotas. The API Grátis documentation provides comprehensive guidance on integrating these keys securely into various applications and programming environments, ensuring that developers can confidently build and deploy solutions using their platform.

Supported authentication methods

API Grátis primarily supports API key authentication. This method is straightforward to implement and manage, making it suitable for a wide range of applications from server-side integrations to client-side scripts where appropriate security measures are in place.

The API key is a long, randomly generated alphanumeric string that uniquely identifies your application or user account with API Grátis. When making a request, this key is transmitted in a designated HTTP header. This method ensures that only authenticated requests are processed by the API, protecting against unauthorized data access and maintaining service integrity.

Method When to Use Security Level
API Key (HTTP Header) For server-to-server communication, backend applications, or client-side applications where the key can be securely stored and transmitted over HTTPS. Moderate (dependent on key secrecy and HTTPS usage)

Getting your credentials

To obtain your API Grátis API key, you must first register for an account on the API Grátis website. Upon successful registration and account activation, your API key will be made available through your developer dashboard. The process generally involves these steps:

  1. Register an Account: Navigate to the API Grátis homepage and sign up for a new account. You may choose between a free tier (up to 300 requests/month) or a paid subscription plan.
  2. Access Developer Dashboard: Log in to your newly created account. Your developer dashboard or settings page will typically contain a section dedicated to API keys.
  3. Generate/Retrieve API Key: Your API key might be automatically generated upon account creation, or you may need to click a button to generate a new key. API Grátis provides a clear interface for managing your keys, including options to regenerate them if compromised.
  4. Copy Your Key: Carefully copy the displayed API key. It is a long string of characters that you will include in your API requests.

It is important to note that API keys should be treated as sensitive information, similar to passwords. Do not hardcode them directly into client-side code that could be publicly accessible, and avoid committing them to version control systems without proper encryption or environment variable management.

Authenticated request example

Once you have your API key, you can include it in your HTTP requests to API Grátis. The API key is typically passed in a custom HTTP header named X-API-Key. Below are examples demonstrating how to make an authenticated request using common programming languages. These examples assume you have replaced YOUR_API_KEY with your actual key and YOUR_ENDPOINT_URL with the specific API Grátis endpoint you wish to access (e.g., a CPF consultation endpoint).

Node.js (using axios)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const endpointUrl = 'https://apigratis.com.br/api/v1/cpf/00000000000'; // Example endpoint

axios.get(endpointUrl, {
  headers: {
    'X-API-Key': apiKey
  }
})
.then(response => {
  console.log('CPF Data:', response.data);
})
.catch(error => {
  console.error('Error fetching CPF data:', error.message);
});

PHP (using curl)

<?php

$apiKey = 'YOUR_API_KEY';
$endpointUrl = 'https://apigratis.com.br/api/v1/cnpj/00000000000100'; // Example endpoint

$ch = curl_init($endpointUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey
]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'CNPJ Data: ' . $response;
}

curl_close($ch);

?>

Python (using requests)

import requests

api_key = 'YOUR_API_KEY'
endpoint_url = 'https://apigratis.com.br/api/v1/cep/00000000' # Example endpoint

headers = {
    'X-API-Key': api_key
}

response = requests.get(endpoint_url, headers=headers)

if response.status_code == 200:
    print('CEP Data:', response.json())
else:
    print(f'Error fetching CEP data: {response.status_code} - {response.text}')

For more detailed examples across other supported languages like Ruby, Go, Java, and C#, refer to the official API Grátis documentation.

Security best practices

Securing your API Grátis API keys is critical to prevent unauthorized access and protect your application and data. Adhering to these best practices will help maintain the integrity of your integrations:

  • Keep API Keys Confidential: Treat your API keys like passwords. Never hardcode them directly into your client-side code (e.g., JavaScript in a public web page) or commit them directly into publicly accessible version control repositories like GitHub without encryption.
  • Use Environment Variables: For server-side applications, store API keys in environment variables rather than directly in your codebase. This allows you to manage keys outside your application's source code, making them easier to rotate and less prone to accidental exposure. Major cloud providers offer specific services for secret management, such as AWS Secrets Manager or Google Cloud Secret Manager.
  • Transmit Over HTTPS: Always ensure that all communications with API Grátis are made over HTTPS (HTTP Secure). This encrypts the data in transit, including your API key, protecting it from interception by malicious actors. API Grátis enforces HTTPS for all its endpoints, but it's crucial for your application to also use it correctly.
  • Implement Server-Side Calls: Whenever possible, make API Grátis calls from your backend server rather than directly from client-side applications. This keeps your API key hidden from end-users and prevents it from being exposed in browser developer tools.
  • Regular Key Rotation: Periodically rotate your API keys. If a key is compromised, rotating it minimizes the window of vulnerability. API Grátis provides functionality in its dashboard to generate new keys and invalidate old ones.
  • Monitor Usage: Regularly monitor your API Grátis usage statistics through your developer dashboard. Unusual spikes in activity could indicate a compromised key or unauthorized use. Prompt investigation can mitigate potential issues.
  • Restrict Key Permissions (If Available): While API Grátis's current model uses a single key for all accesses, if future iterations or other services offer granular permissions, always apply the principle of least privilege. Grant only the necessary permissions required for a specific application or service.
  • Secure Development Environment: Ensure that your development environment is secure. This includes using strong passwords, keeping software updated, and being mindful of where sensitive credentials are stored during development and testing phases.