# Read the ordered agent onboarding journey

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

Contract status: **implemented**. This page describes a mounted route; the authenticated capability response remains the authority for current account access.

## Request

`GET /api/agent/v1/onboarding`

Operation ID: `getAgentOnboarding`

Send a short-lived access token obtained through [auth.md](https://neotask.ai/auth.md) for `https://neotask.ai/api/agent` in the `Authorization: Bearer` header. The token must include `neotask:catalog:read`.





## Response

The current identity, execution modes, progress state, safe resource summaries, and next actions. The JSON schema is `AgentOnboardingResponse` in [OpenAPI](https://neotask.ai/openapi.yaml).

- The response is derived from the verified principal, current account snapshot, effective operation registry, runner state, and bounded tenant-scoped resource queries.
- Onboarding is read-only guidance. It is not a client checklist and cannot grant access or mark a milestone complete.
- No tenant, user, credential, provider secret, or internal database identifier is accepted from or returned to the caller.
- The same derived service powers REST GET /api/agent/v1/onboarding and the neotask_onboarding MCP tool.
- A pre-claim service-auth identity is not fabricated by this route; claim_pending appears only when an upstream verified middleware claim is present.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 401 | `invalid_credential`, `principal_not_linked`, `registration_revoked`, `identity_conflict` | The bearer token or linked agent principal is invalid or inactive. | Register, refresh, or claim through the documented Auth.md flow, then retry with a new token. |
| 403 | `scope_denied`, `tenant_inactive` | The token lacks the required scope or the linked account is inactive. | Read the error code. Request the documented scope or ask the user to restore account access. |
| 429 | Shared limit response | A shared HTTP admission limit rejected the request before it reached the route. | Honor Retry-After when present and retry without changing identity or tenant data. |
| 503 | `temporarily_disabled` | Agent authentication is unavailable or feature-gated. | Do not bypass authentication. Retry only after the returned guidance or launch state changes. |

## Related resources

- [Agent API index](https://neotask.ai/docs/llms.txt)
- [OpenAPI JSON](https://neotask.ai/openapi.json)
- [Arazzo quickstart](https://neotask.ai/arazzo.yaml)
- [Knowledge manifest](https://neotask.ai/agent-public-contracts/v1/knowledge-manifest.json)