When making HTTP requests with cURL, you often need to include custom headers. Headers are important when sending additional information to the server, like authentication tokens, content types, or even user-agent details. Without the correct headers your request might fail or return incomplete data errors such as: error 403 or 500.
In this guide, we’ll break down how to send headers with cURL, why they matter, and provide real-world examples you can use right away. We will make sure to cover both how to send a single header and multiple headers.
Why Do We Need to Send Headers with cURL?
Headers carry important metadata that tells the server how to handle your requests. Without them, some APIs or websites won’t even respond. Here are a few common scenarios where headers are critical and needs to be included:
- Authentication: Sending API keys or Bearer tokens for secure access.
- Content Type: Letting the server know you’re sending JSON, form data or plain text.
- User-Agent: Mimicking a browser or custom client so your request doesn’t get blocked.
- Custom Headers: Passing special instructions or unique identifiers.
Think of headers as an “ID badge” for your requests, it’s an identifier of who you are and what to expect in return.
How to Send a Single Header with cURL
Adding a single header in cURL is a simple and straightforward task, You use the -H or –header option, followed by the header name and value.
Basic syntax:
Example 1: Custom User-Agent
Servers often check the User-Agent header to identify the client making the request. By default, cURL uses something like this curl/8.0.1, but you change it.
When is this useful?
- You want your request to look like it’s coming from a browser.
- You’re dealing with APIs that require a specific user-agent.
Example 2: Sending an API Key
Some APIs require authentication via an API key in the header:
Use this when:
- Accessing private APIs that need tokens.
- Testing OAuth or JWT-based authentication.
Example 3: Content-Type Header
When sending data, you often need to specify the content type:
Why do we use content-type? On many occasions the server might not know how to parse your request body, so content-type is like a heads up for it.
Why Use Single Headers?
- To customize requests for APIs.
- To simulate browser requests for scraping.
- To send authorization credentials.
- To define content types for POST/PUT requests.
Pro Tip: You actually can use -H multiple times for multiple headers, which we’ll cover next.
How to Send Multiple Headers with cURL
Most of the time, one header is not enough. You might need to send an Authorization header and a content-type header at the same time, With cURL, you can simply repeat the -H flag for each header.
Basic syntax:
Example: Sending User-Agent and Authorization headers
Why Would You Need Multiple Headers?
- API Authentication: Combine Authorization with Accept to specify both credentials and response format.
- Version Control: Some APIs require X-API-Version headers to select which version you’re using.
- Content Negotiation: Include Accept-Language and Accept-Encoding to influence the response language and compression.
Pro Tip: Order doesn’t matter, but readability does. As a developer it’s super important to write clean, maintainable commands so using line breaks (\) is a key.
How to Load Headers from a File with cURL
I only learned the following trick five years into the industry; it’s one I’d learned much sooner. If you are sending many headers — or reusing the same set across multiple requests — putting them in a file is a cleaner approach. cURL can read headers from a file using the -H flag with @filename.
Header file format: Each header on a new line.
And here we are going to use it with this basic syntax:
Why Use a File for Headers?
- Maintainability: Easily update headers without touching your scripts.
- Reusability: Use the same headers for multiple requests or environments.
- Clarity: Keeps long cURL commands clean and readable.
This approach is super handy when working with APIs that require many headers or custom authentication schemes.
How to Debug and Verify Headers Sent with cURL
Obviously, when working with headers you want to make sure that they are being sent correctly. cURL provides verbose output that lets you inspect both requests and responses.
Basic Syntax:
Example:
The -v (verbose) flag shows:
- The exact header sent to the server.
- The headers received in the response
- TLS handshake information and connection details
Why is Debugging Useful?
- Debugging: Ensure your API key, user-agent, or other headers are correctly applied.
- Testing: Compare cURL requests with tools like Postman to verify your headers produce the same behavior.
Pro tip: You can combine verbose mode with -i to include the response headers in the output, making it easier to debug requests-response pairs.
Best Practices for Using cURL to Send Requests with Headers
Sending headers might seem straightforward, but believe me following a few best practices can save you headaches later, especially when working with APIs or scraping data.
Keep Sensitive Data Secure
- Avoid hardcoding API keys or passwords in your scripts (I don’t always follow my own advice, but I do eventually change it.)
- Use environment variables or external congestion control to store the sensitive data.
Reuse Headers with Files
- For multiple headers or repeated, store them in a file where you can reuse them, load them with -H @filename.
- Always make your scripts cleaner especially when working with a team.
Debug Before Automating
- Use -v to verify headers and troubleshoot request issues.
- Use Postman to compare the behaviours to make sure they behave as expected.
Combine with Others Flags
- Use -L to follow redirects when headers might affect the final URL.
- Use –compressed to request compressed responses for faster downloads.
Test Incrementally
- Testing with a single header first then going to multiple is the best approach to do, the reason is that it will be easier for you to debug.
- This is super important for authentication and content negotiation.
Following these best practices ensures your requests are secure, maintainable, and predictable.
Conclusion
Countless hours of important developer time has been saved since the introduction of multiple headers. It makes life easier when accessing APIs, scraping websites, or debugging network traffic.
Key takeaways:
- Use -H to send single or multiple headers
- Store headers in a file cleaner, reusable commands.
- Always debug with -v and compare results with tools like Postman.
- Handle sensitive data securely with environment variables or config files.
- Customize headers for authorization, content type, API versioning.
By using headers you gain full control over your cURL requests, making your work more efficient and reliable just like a pro! Happy coding!