---
title: "Start agent-initiated, human-authorized provisioning"
method: POST
path: "/api/agent-onboarding/request"
tags: ["onboarding"]
---

# Start agent-initiated, human-authorized provisioning

`POST /api/agent-onboarding/request`

## Request

- Base URL: `https://www.spendline.ai`
- URL: `https://www.spendline.ai/api/agent-onboarding/request`
- Auth: none required

PUBLIC: no credential required, because the caller has none yet.

Issues NO credential. It emails the named human, who must approve in a browser.
Shaped after RFC 8628 (OAuth 2.0 Device Authorization Grant).

An agent cannot create an account, cannot choose a password, and cannot approve
its own request.

## Request body

- object
  - `human_email` string, email, required: The human who owns this application. They receive the approval email.
  - `agent_name` string: How to identify you to the human.
  - `intended_use` string: Plain sentence shown to the human.
  - `proposed_budget` object: Optional initial budget to PROPOSE. The human sees the exact numbers and approves or skips it; if approved it is created under their authority.
    - `scope_type` 'org' | 'team' | 'agent' | 'customer'
    - `scope_id` string
    - `monthly_limit_usd` number
    - `strict_mode` boolean

## Response `201`

Request created. Poll for the outcome.

- object
  - `request_id` string, uuid
  - `device_code` string: Your poll credential. Shown once.
  - `user_code` string: What the human sees. Not a credential.
  - `verification_uri` string, uri
  - `verification_uri_complete` string, uri
  - `interval` integer: Seconds between polls.
  - `expires_in` integer
  - `status` string
  - `human_action_required` string

## Other responses

- `400`: human_email missing/invalid, or a malformed proposed_budget.
- `429`: Rate limited.
- `503`: This deployment cannot send the authorization email, so the flow cannot complete. Fall back to asking the human to create a key in the dashboard.

---

[API](https://skmtc.dev/spendline/apis/spendline-api.md) · [All operations](https://skmtc.dev/spendline/apis/spendline-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spendline/apis/spendline-api/revisions/eb22b9415a28?raw)