API Authentication & Custom Headers

1. A Quick Refresher on HTTP Headers

Before we dive into the Go implementation, let's briefly review the role of HTTP headers. They are key-value pairs sent with every HTTP request and response, carrying metadata that tells the client and server how to handle the communication.

While many headers exist, our primary focus today is on the Authorization header, which is the standard way to carry credentials for API access.

The Bearer scheme is simple: you present a token, and the server "bears" (accepts) it as proof of your identity and permissions, without needing complex cryptographic handshakes for every request.

2. Building a Request with Custom Headers in Go

So far, we've used convenience functions like http.Get(). To add headers, we need more control. This involves creating the request object ourselves before sending it. The process is:

1. Create a request object using http.NewRequest().
2. Add headers to the request's Header field.
3. Send the request using an http.Client.

The req.Header field on an *http.Request object has a Set(key, value) method that makes adding headers straightforward.

As you can see, the pattern is simple and repeatable for any header you need to add.

3. A DevOps Best Practice: Managing API Tokens Securely

Your experience with scripting and automation has surely taught you that hardcoding secrets like API keys or tokens into your code is a significant security risk. A more secure and flexible approach is to load them from the environment.

Go's standard library os package provides the Getenv() function for this purpose. This is the idiomatic way to handle secrets in Go applications, allowing your tool to be configured for different environments (dev, staging, prod) without changing the code.

4. Putting It All Together: A Practical Example

Let's combine what we've learned into a practical program. We will write a small Go tool that fetches your user profile from the GitHub API. This requires authentication, so it's a perfect use case.

Here's the plan for our program:

1. Define a struct to hold the GitHub user data (connecting to our last lesson).
2. Read a GitHub Personal Access Token from an environment variable named GITHUB_TOKEN.
3. Create an http.Client with a reasonable timeout.
4. Construct a new GET request to the GitHub API.
5. Set the Authorization header with the token.
6. Set a custom User-Agent header, which is a good practice (and required by the GitHub API).
7. Execute the request, check for errors and non-200 status codes.
8. Parse the JSON response into our struct and print the result.

Here is the complete code. You can save this as main.go.

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

// GitHubUser represents a subset of the fields from the GitHub /user API response.
type GitHubUser struct {
	Login     string `json:"login"`
	Name      string `json:"name"`
	PublicRepos int    `json:"public_repos"`
}

func main() {
	// 1. Read the token from an environment variable.
	token := os.Getenv("GITHUB_TOKEN")
	if token == "" {
		fmt.Println("Error: GITHUB_TOKEN environment variable not set.")
		os.Exit(1)
	}

	// 2. Create a custom HTTP client.
	client := &http.Client{
		Timeout: 10 * time.Second,
	}

	// 3. Create the request object.
	req, err := http.NewRequest("GET", "https://api.github.com/user", nil)
	if err != nil {
		fmt.Printf("Error creating request: %v\n", err)
		os.Exit(1)
	}

	// 4. Set the required headers.
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("User-Agent", "Go-DevOps-Tool/1.0")
	// GitHub API recommends this header for API versioning.
	req.Header.Set("Accept", "application/vnd.github.v3+json")

	// 5. Execute the request.
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Error making request: %v\n", err)
		os.Exit(1)
	}
	defer resp.Body.Close()

	// 6. Check for a non-successful status code.
	if resp.StatusCode != http.StatusOK {
		fmt.Printf("Error: received non-200 status code: %d\n", resp.StatusCode)
		os.Exit(1)
	}

	// 7. Decode the JSON response.
	var user GitHubUser
	if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
		fmt.Printf("Error decoding JSON: %v\n", err)
		os.Exit(1)
	}

	// 8. Print the result.
	fmt.Printf("Successfully fetched data for user: %s (%s)\n", user.Name, user.Login)
	fmt.Printf("Public Repositories: %d\n", user.PublicRepos)
}

To run this code:

1. Generate a GitHub Personal Access Token with the read:user scope.
2. Set the environment variable and run the program from your terminal:

   export GITHUB_TOKEN="your_github_token_here"
   go run main.go
   

You should see your GitHub profile information printed to the console.

// Add this line inside the main function, for example, after setting the 'Accept' header.
req.Header.Set("X-Request-ID", "devops-tool-12345")

Conclusion

You have now mastered a critical skill for building powerful DevOps tools: authenticating with and customizing requests to modern APIs. By constructing requests manually and setting headers, you can interact with virtually any secured REST API.

Key Takeaways:

• Use http.NewRequest() to create a request object that you can customize before sending.
• Modify request headers using the req.Header.Set("Key", "Value") method.
• The Authorization: Bearer <token> header is the standard for token-based authentication.
• Always load secrets like API tokens from the environment using os.Getenv() rather than hardcoding them.
• Setting a descriptive User-Agent header is a good practice for identifying your tool's API traffic.

Next Up

Our requests are becoming more robust, but what happens when a network is slow or an API is temporarily unavailable? A simple timeout isn't always enough. In our next lesson, we will explore Go's context package to manage request lifecycles and implement timeouts and cancellation, giving you fine-grained control over your network operations.