Skip to main content

​
Overview

Halo API supports two authentication methods:
  1. Basic Authentication - Username and password
  2. Bearer Token Authentication - Personal Access Tokens (PAT) or JWT tokens
Most API endpoints require authentication. Public content endpoints may allow unauthenticated access for read operations, but authentication is required for user-specific data or write operations.

​
Basic Authentication

Basic Authentication uses your Halo username and password. This method is suitable for:
  • Development and testing
  • Server-to-server integrations in trusted environments
  • Quick API exploration
Basic Authentication sends credentials with every request. Always use HTTPS in production to protect your credentials. For production applications, Personal Access Tokens are strongly recommended.

​
How It Works

Basic Authentication requires sending your credentials in the Authorization header using Base64 encoding: 
Authorization: Basic base64(username:password)

​
Example Request

curl -X GET 'http://localhost:8091/api/v1alpha1/posts' \
  -H 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  -H 'Content-Type: application/json'

​
Basic Auth Parameters

​
Authorization
string
required
The Basic authentication header in the format: Basic base64(username:password)To create the value:
  1. Combine username and password with a colon: username:password
  2. Encode the string in Base64
  3. Prefix with Basic

​
Personal Access Tokens (PAT)

Personal Access Tokens are the recommended authentication method for production applications. PATs provide:
  • Enhanced security - No need to share your password
  • Granular permissions - Can be scoped to specific operations
  • Easy revocation - Revoke tokens without changing your password
  • Audit trails - Track API usage per token

​
Creating a Personal Access Token

  1. Log in to your Halo admin dashboard
  2. Navigate to User Center > Personal Access Tokens
  3. Click Generate New Token
  4. Provide a descriptive name for the token
  5. Set token expiration (optional but recommended)
  6. Select permissions/scopes for the token
  7. Click Generate
  8. Copy and save the token immediately - you won’t be able to see it again
Store your Personal Access Tokens securely. Treat them like passwords - never commit them to version control or share them publicly.

​
Using Personal Access Tokens

Include the token in the Authorization header as a Bearer token: 
Authorization: Bearer your-personal-access-token

​
Example Request with PAT

curl -X GET 'http://localhost:8091/api/v1alpha1/posts' \
  -H 'Authorization: Bearer pat_1234567890abcdef' \
  -H 'Content-Type: application/json'

​
Bearer Token Parameters

​
Authorization
string
required
The Bearer token header in the format: Bearer your-tokenThe token can be:
  • A Personal Access Token (recommended)
  • A JWT token from the authentication endpoint

​
Token Management Best Practices

​
Security Recommendations

1

Use Environment Variables

Store tokens in environment variables, never hardcode them:
export HALO_API_TOKEN="pat_1234567890abcdef"
2

Set Expiration Dates

Always set expiration dates for tokens. For production, use short-lived tokens (30-90 days) and rotate them regularly.
3

Use Minimal Permissions

Grant tokens only the permissions they need. Don’t use admin tokens for read-only operations.
4

Monitor Token Usage

Regularly review token usage in your Halo admin dashboard and revoke unused tokens.
5

Rotate Tokens Regularly

Implement a token rotation policy, especially for production environments.

​
Revoking Tokens

If a token is compromised or no longer needed:
  1. Log in to Halo admin dashboard
  2. Navigate to User Center > Personal Access Tokens
  3. Find the token in the list
  4. Click Revoke
  5. Confirm the revocation
Revoked tokens become invalid immediately. Any API requests using a revoked token will receive a 401 Unauthorized response.

​
Authentication Errors

​
Common Error Responses

​
401 Unauthorized - Missing Authentication

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Authentication required",
  "path": "/api/v1alpha1/posts"
}
Solution: Include the Authorization header in your request.

​
401 Unauthorized - Invalid Credentials

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid username or password",
  "path": "/api/v1alpha1/posts"
}
Solution: Verify your username and password are correct.

​
401 Unauthorized - Invalid Token

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired token",
  "path": "/api/v1alpha1/posts"
}
Solution: The token may be invalid, expired, or revoked. Generate a new token.

​
403 Forbidden - Insufficient Permissions

{
  "status": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to access this resource",
  "path": "/api/v1alpha1/users"
}
Solution: Your account or token doesn’t have the required permissions. Request higher privileges or use an admin account.

​
Testing Authentication

You can test your authentication credentials with a simple API call: 
curl -X GET 'http://localhost:8091/api/v1alpha1/posts' \
  -H 'Authorization: Bearer your-token' \
  -H 'Content-Type: application/json' \
  -w '\nHTTP Status: %{http_code}\n'
A successful response (HTTP 200) indicates your authentication is working correctly.

​
Next Steps

API Overview

Learn about API architecture and versioning

Public APIs

Explore public content APIs

Console APIs

Manage your Halo instance

Extension APIs

Access custom extensions

Build docs developers (and LLMs) love

Get started for freeTalk to us