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://api.agentsworklog.dev/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 $AGENTSWORKLOG_TOKEN

REQUEST

curl https://api.agentsworklog.dev/v1/activities \
  -H "Authorization: Bearer $AGENTSWORKLOG_TOKEN" \
  -G -d "repo=acme/web"

MISSING TOKEN 401 Unauthorized

{
  "error": {
    "type": "unauthorized",
    "message": "Missing or invalid bearer token."
  }
}

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 403 Forbidden — the API never reveals whether the repo even exists beyond what GitHub would tell you.

NO ACCESS 403 Forbidden

{
  "error": {
    "type": "forbidden",
    "message": "Token cannot access repo acme/web."
  }
}

Obtaining a token

Install the AgentsWorklog GitHub App on the repositories you want covered, then generate a token from the dashboard. The token inherits 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.

ENVIRONMENT

export AGENTSWORKLOG_TOKEN="awl_live_9Fq0Zt4…"