auth.md

auth.md

This file tells AI agents how to start a Buddy Punch free trial for a person who asked them to.

Buddy Punch is time tracking, scheduling and payroll software for small and mid-sized businesses.

Discover

You can find this sign-up lane from the API itself, without this file:

  1. Fetch https://api2.buddypunch.com/.well-known/oauth-protected-resource, the API's resource metadata. The MCP endpoint points there too: POST /mcp without credentials answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api2.buddypunch.com/.well-known/oauth-protected-resource".
  2. Besides the usual OAuth fields (resource, authorization_servers, scopes_supported), it has an agent_auth block:
    • skill: this file.
    • signup_endpoint: where the lane starts (step 1 below).
    • identity_types_supported: [ "anonymous" ]. You don't need an identity or credentials of your own.
    • owner_confirmation: "email". The owner confirms the trial from their inbox.

What you get

A free 14-day trial of Buddy Punch Pro for the owner's company, and an API key for that account only. The owner must confirm by email before they can log in, and agrees to our terms themselves when they do.

Until the owner confirms:

When the owner confirms, the key gets the trial's full permissions and no expiry, unless the owner turns it off. That includes MCP (Pro includes it). Onboarding and offboarding still don't work while the account is on a free trial.

After the trial, the key keeps working only while the account pays for Pro or Advanced. Paying for Starter, ending the trial without paying, or moving down to Starter later turns the key off for good. The owner can see the key, turn it off, and make new keys under Settings in Buddy Punch.

If the owner doesn't confirm within 7 days, or presses "This wasn't me", the account is closed and the key stops working. The owner can also turn the key off from the confirm page without confirming.

If you can't make these requests

Use this if you can only read web pages, or can't run the three requests below in code.

  1. Send the owner this link: https://app.buddypunch.com/account/register/ProMonthly?utm_source=ai-agent&utm_medium=auth-md
  2. Tell them it starts the same 14-day Pro trial with no credit card. They create their own login and agree to our terms on that page, which takes about two minutes.
  3. Once they're in, connect over MCP at https://api2.buddypunch.com/mcp. The owner approves access by signing in to Buddy Punch. MCP clients find the authorization server at https://api2.buddypunch.com/.well-known/oauth-protected-resource.
  4. Or ask the owner for an API key. They make one in Buddy Punch under Settings > Integrations > Developer API > Manage API Keys. Send it as Authorization: Bearer <apiKey> to https://api2.buddypunch.com.

Never ask the owner for their password.

Before you register: the owner's yes

Show the owner these two documents and get a clear yes from them before you set ownerAcceptedTerms:

Never set ownerAcceptedTerms to true on your own. We record that an agent said yes for the owner, when, and which versions, and the owner agrees again themselves when they confirm.

How to register

Three steps, each a POST with a JSON body. Do them back to back: the puzzle must be answered within 30 seconds, and the token works for 60 seconds.

Step 1: Get a puzzle

POST /agent-signup/puzzle HTTP/1.1
Host: api2.buddypunch.com
Content-Type: application/json

{}

Returns 201 with id, kind, instructions, input, expiresAt, expiresInSeconds (30) and answerUrl. Kinds: multiply, reverse, count, sort, binary. Read instructions and compute the answer from input in code.

answerUrl is a path, not a full address: add the API host, https://api2.buddypunch.com, in front of it.

Step 2: Answer it

POST /agent-signup/puzzle/{id}/answer HTTP/1.1
Host: api2.buddypunch.com
Content-Type: application/json

{ "answer": "<your answer>" }

A puzzle takes one answer. A right answer returns 200 with a one-time token, expiresAt, expiresInSeconds (60) and signupUrl, which is also a path to add the host to. A wrong, late or second answer returns 400 (puzzle_answer_wrong or puzzle_not_open): ask for a new puzzle.

Step 3: Create the account

POST /agent-signup/account HTTP/1.1
Host: api2.buddypunch.com
Content-Type: application/json

{
  "token": "<token from step 2>",
  "ownerFirstName": "Pat",
  "ownerLastName": "Owner",
  "ownerEmail": "pat@example.com",
  "companyName": "Owner Plumbing",
  "actingForOwner": true,
  "ownerAcceptedTerms": true,
  "payPeriod": "monthly"
}

Answers:

This step can take 15 seconds or more. Wait at least 30 seconds before giving up.

If it times out, the account may have been created, but its key is lost for good: it is only ever shown in this answer. Don't retry right away. Ask the owner to look for an email titled "Confirm your Buddy Punch trial". If one arrived, the trial exists and the owner can confirm it (they can make a new key in Settings). Only if no email arrives within a few minutes, try again from step 1; a retry while a trial is waiting answers 202.

Then tell the owner to check their inbox for "Confirm your Buddy Punch trial".

Errors

Every error answer has the same shape, wrapped in an error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "ownerEmail must be the owner's email address.",
    "param": "ownerEmail",
    "signupPageUrl": "https://app.buddypunch.com/Account/Register",
    "requestId": "req_..."
  }
}
Status error.code What to do
400 puzzle_answer_wrong, puzzle_not_open Get a new puzzle
400 token_invalid Solve a new puzzle
400 parameter_invalid Fix the field named in param, then solve a new puzzle
429 agent_signup_limit_exceeded Wait retryAfterSeconds, then start again from step 1
500 agent_signup_failed Nothing was created and no key was given; start again from step 1
500 internal_error Something failed on our side; wait a minute and start again from step 1
503 agent_signup_unavailable Agent sign-up is off; follow "If you can't make these requests"

Request bodies over 8 KB are refused unread.

Limits

A refusal is 429 with agent_signup_limit_exceeded, Retry-After and retryAfterSeconds saying when to try again.

When the lane is off

Every step answers 503 with agent_signup_unavailable and a signupPageUrl. Use "If you can't make these requests" above instead: send the owner that sign-up link, then connect once they're in.

Using the key

Send it as Authorization: Bearer <apiKey> to https://api2.buddypunch.com. The API is described in the OpenAPI file at https://api2.buddypunch.com/swagger/v1/swagger.json.

When the key stops working

A 401 means the key is off: it expired before the owner confirmed, the owner turned it off or closed the trial, or the account is no longer on a plan that keeps it. Signing up again with the same email gives you no key. Tell the owner; they can make a new key under Settings in Buddy Punch if they want you to keep working.