Documentation
Everything you need to integrate Paitify into your AI agent stack.
Quickstart
- Sign up and create a company account.
- Generate an API key from the dashboard Settings page.
- Create an agent via
POST /v1/agents. - Call
POST /v1/authorizebefore every spend event. - Pass the returned JWT to your payment processor for offline verification.
quickstart.sh
# Start dependencies docker compose up postgres redis -d # Run the backend ./gradlew bootRun # Install & run the frontend cd frontend && npm install && npm run dev
Authentication
All API requests require an X-API-Key header with a key generated from your dashboard. Keys are stored as bcrypt hashes — only the prefix is stored in plain text for efficient lookup.
curl -H "X-API-Key: ag_live_xxxxxxxxxxxx" \
https://api.paitify.ai/v1/agentsAPI Reference
Authorization (Two-Phase)
POST
/v1/authorizeSubmit a spend request for policy evaluation. Returns APPROVED or DENIED with a signed JWT.POST
/v1/authorize/{id}/confirmConfirm a pending authorization after payment succeeds. Finalizes spend counters.POST
/v1/authorize/{id}/voidVoid a pending authorization. Rolls back spend counters.GET
/v1/budget/{agentId}Get remaining budget for an agent across all configured periods.Agents
POST
/v1/agentsCreate an agent.GET
/v1/agentsList all agents for your company.GET
/v1/agents/{id}Get a single agent by ID.DELETE
/v1/agents/{id}Delete an agent.GET
/v1/agents/{id}/policiesList policies assigned to an agent.Policies
POST
/v1/policiesCreate a policy (company-wide or agent-scoped).GET
/v1/policiesList all policies for your company.GET
/v1/policies/{id}Get a policy by ID.PUT
/v1/policies/{id}Update a policy.DELETE
/v1/policies/{id}Delete a policy.Approvals
GET
/v1/approvalsList pending human-approval requests.POST
/v1/approvals/{id}/approveApprove a held authorization.POST
/v1/approvals/{id}/denyDeny a held authorization.API Keys
POST
/v1/api-keysGenerate a new API key.GET
/v1/api-keysList API keys for your company.DELETE
/v1/api-keys/{id}Revoke an API key.JWKS
GET
/.well-known/jwks.jsonRSA public key set for verifying issued JWTs. No auth required.Clerk Configuration
Paitify uses Clerk for frontend authentication. Set the following environment variables in frontend/.env.local:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_... CLERK_SECRET_KEY=sk_live_... NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/overview NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/overview
Configure backend Clerk JWT validation in application.yml via CLERK_ISSUER_URI and CLERK_JWKS_URI env vars.
Interactive API Explorer
When running locally, Swagger UI is available at http://localhost:8080/swagger-ui.html. The OpenAPI spec is at http://localhost:8080/v3/api-docs.