> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnpj-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate your API requests

# Authentication

All API requests require an authentication token. We offer both free and paid tokens.

## Free tokens

Free tokens are available to all users with a limit of **5 queries per minute** and access to all endpoints. For higher needs, paid tokens offer higher limits and dedicated support. See [Rate Limits](/en/limites-de-uso) for more details.

## Creating an account

See [Create Account](/en/criar-conta) for instructions on how to get your token.

## Authentication methods

### Via URL parameter (recommended)

The preferred authentication method is to send the token as a `token` URL parameter:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cnpj-api.com/v1/cnpj/12345678000195?token=YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.cnpj-api.com/v1/cnpj/12345678000195?token=YOUR_TOKEN'
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.cnpj-api.com/v1/cnpj/12345678000195',
      params={'token': 'YOUR_TOKEN'}
  )
  data = response.json()
  ```
</CodeGroup>

### Via HTTP header

**Alternatively**, send the token in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_TOKEN" \
    "https://api.cnpj-api.com/v1/cnpj/12345678000195"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.cnpj-api.com/v1/cnpj/12345678000195',
    {
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.cnpj-api.com/v1/cnpj/12345678000195',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  data = response.json()
  ```
</CodeGroup>

## Error responses

| Code  | Description              |
| ----- | ------------------------ |
| `401` | Invalid or missing token |
| `429` | Request limit exceeded   |

When receiving `429`, wait 1 minute before retrying. Paid tokens have higher limits.