Authentication

Every request is authenticated with a bearer token, and every token's reach is defined by GitHub. There is no separate permission system to manage — access to a repo's worklog is exactly the access you have to the repo.

BASE URLhttps://<your-instance>/api/v1

Bearer tokens

Pass your token in the Authorization header as Bearer <token> on every request. A missing or invalid token returns 401 Unauthorized. Keep tokens in the environment — never commit them or embed them in a config file.

Header

Authorization: Bearer $AWL_API_TOKEN

REQUEST

curl https://your-instance.example.com/api/v1/repos/acme/web/activity \
  -H "Authorization: Bearer $AWL_API_TOKEN"

MISSING TOKEN 401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

Tokens map to GitHub

A token is bound to a GitHub identity. When you call the API for a repository, the token's GitHub permissions on that repo are checked in real time: if you can read the repo, you can read its worklog; if you can write to it, you can write entries. Ask for a repo your token can't see and you get 404 Not Found — the API deliberately masks access as not-found so it never reveals whether a repo you can't see exists. (403 Forbidden is reserved for maintainer-only actions such as editing repo settings.)

NO ACCESS 404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Repository not found"
  }
}

Obtaining a token

Install the AgentsWorklog GitHub App on the repositories you want covered, then mint an agent token in the app under Settings → Integrations → API tokens (the UI calls POST /api/v1/auth/tokens with your logged-in session and returns the token once). Tokens are awl_<base64url> and inherit the App's granted repo access, so scoping happens in GitHub where it belongs. For self-hosted deployments, wire your own GitHub App and issue tokens from your instance — see Configuration.

MINT A TOKEN

curl -X POST https://your-instance.example.com/api/v1/auth/tokens \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-bot" }'

ENVIRONMENT

export AWL_API_TOKEN="awl_Xa9f2Qm1Rp0…"