Authorization
All Heylock API requests require an agent key. Each agent has exactly one key.
How it works
Include your agent key in the Authorization header of every request. The value is the raw key string (no Bearer prefix).
1await fetch('https://heylock.dev/api/v1/message', {
2 method: 'POST',
3 headers: {
4 Authorization: process.env.HEYLOCK_AGENT_KEY,
5 'Content-Type': 'application/json',
6 },
7 body: JSON.stringify({ content: 'Hello' })
8});Key lifecycle
- Generate the key in the dashboard after your agent finishes indexing.
- Store it once. You can't view it again.
- Regenerating immediately revokes the previous key. All requests using the old key start failing with 401.
- One key per agent. Rotating creates the new one and invalidates the old one.
Server vs client usage
Prefer sending requests from your server (Next.js Route Handler, API route, edge function, backend service). This keeps the key out of the browser and logs.
Environment variables
Store the key in an environment variable like HEYLOCK_AGENT_KEY. Don't hardcode it. For Next.js, reference it inside server code only so it isn't bundled client-side.
1// next.config.js (do NOT expose the key via NEXT_PUBLIC_*)
2// Use it only in server code (Route Handler / getServerSideProps / server action)
3export async function sendMessage(message){
4 const response = await fetch('https://heylock.dev/api/v1/message', {
5 method: 'POST',
6 headers: {
7 Authorization: process.env.HEYLOCK_AGENT_KEY,
8 'Content-Type': 'application/json'
9 },
10 body: JSON.stringify({ content: message })
11 });
12
13 if(response.status === 401) throw new Error('Invalid agent key');
14
15 return response.json();
16}Error responses
You'll get a structured JSON body when authorization fails. Handle both 400 (missing / malformed header) and 401 (invalid or revoked key).
1{
2 "error":"INVALID_AGENT_KEY",
3 "message":"Agent key is not valid. Please check the provided key or regenerate."
4}Common mistakes
- Using an old key after rotation (results in 401).
- Omitting the
Authorizationheader (400). - Adding a
Bearerprefix (it must be the raw key). - Exposing the key in client logs or error analytics.
Security practices
- Mask keys in logs and monitoring dashboards.
- Rotate if you suspect exposure. Update all deployments immediately.
- Scope access in your own backend: don't forward raw keys to untrusted clients.
Using with routes
All endpoints share the same authentication model: /message, /rewrite, /sort, /should-engage, and /limits.
1const response = await fetch('https://heylock.dev/api/v1/rewrite', {
2 method: 'POST',
3 headers: {
4 Authorization: process.env.HEYLOCK_AGENT_KEY,
5 'Content-Type': 'application/json'
6 },
7 body: JSON.stringify({
8 text: 'English bad',
9 instructions: 'Fix grammar'
10 })
11});