> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-fjmorr-1782499519-e1e0dbe.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Start an authorization session > Initiates an OAuth flow for the caller. strategy is optional and defaults to REUSE (return an existing token when scopes match); use CREATE to force a new OAuth flow. Status values: COMPLETED — a valid token is available and the response includes token (HTTP 200); PENDING — the user must visit verification_url to authorize (HTTP 201, includes session id and Location header); CONNECTION_REQUIRED — no usable token or connection exists for the provider; TOKEN_EXPIRED — the stored token expired and cannot be refreshed, re-authorize. is_default defaults to true; set false when adding a secondary account with strategy CREATE. token_id targets a specific stored token in multi-account flows. ## OpenAPI ````yaml /langsmith/headless-fleet-openapi.json post /v1/fleet/auth-sessions openapi: 3.0.0 info: contact: {} description: > The Fleet API is a headless interface for building and running agents — create and configure agents, manage their connections and secrets, run threads, and wire up triggers. Paths are service-native (e.g. `/v1/fleet/agents`). Self-hosted deployments reach them through the gateway under an `/api` prefix (e.g. `/api/v1/fleet/agents`). ## Authentication Every request must carry **one** credential: | Scheme | Header | Value | | --- | --- | --- | | API key | `X-Api-Key` | A LangSmith API key (`lsv2_…`). | | Session token | `Authorization` | `Bearer `. | Workspace-scoped endpoints additionally require **`X-Tenant-Id`**, set to the workspace (tenant) UUID the request operates in. Organization- and identity-scoped endpoints omit it. ## Errors Errors follow [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) (Problem Details) and use one JSON shape across every endpoint: ```json { "type": "about:blank", "code": "agent_not_found", "detail": "No agent exists with that ID.", "status": 404 } ``` - `type` — URI identifying the error type. Currently always `about:blank` (the RFC 7807 default); branch on `code`, not `type`. - `code` — stable, machine-readable identifier. Branch on this rather than matching `detail`. - `detail` — human-readable explanation. Proxied endpoints also echo it as `message`. - `status` — mirrors the HTTP status code. | Status | Meaning | | --- | --- | | `400` | Malformed request or failed validation. | | `401` | Missing or invalid credentials. | | `403` | Authenticated, but not permitted to access this resource. | | `404` | The resource does not exist or is not visible to your workspace. | | `409` | Conflicts with current state (e.g. a duplicate). | | `422` | Well-formed but semantically invalid. | | `500` | Unexpected server error. | | `502` / `503` | An upstream dependency failed or was unavailable. Retries are usually safe. | ## Pagination List endpoints return a fixed-size page and an opaque cursor: ```json { "items": [ ], "next_cursor": "eyJ…" } ``` - `page_size` — items per page, `1`–`100` (default `20`). - `cursor` — pass the previous response's `next_cursor` to fetch the next page. An absent or empty `next_cursor` means there are no more results. Cursors are opaque — don't construct or parse them. title: Fleet API version: v1 servers: - url: / security: [] tags: - name: agents - name: agent connections - name: threads - name: skills - name: auth - name: integrations - name: secrets - name: models - name: tenants - name: users paths: /v1/fleet/auth-sessions: post: tags: - auth summary: Start an authorization session description: >- Initiates an OAuth flow for the caller. strategy is optional and defaults to REUSE (return an existing token when scopes match); use CREATE to force a new OAuth flow. Status values: COMPLETED — a valid token is available and the response includes token (HTTP 200); PENDING — the user must visit verification_url to authorize (HTTP 201, includes session id and Location header); CONNECTION_REQUIRED — no usable token or connection exists for the provider; TOKEN_EXPIRED — the stored token expired and cannot be refreshed, re-authorize. is_default defaults to true; set false when adding a secondary account with strategy CREATE. token_id targets a specific stored token in multi-account flows. requestBody: content: application/json: schema: $ref: '#/components/schemas/auth.CreateSessionRequest' description: Session details required: true responses: '200': description: Existing token reused; no new session created. content: application/json: schema: $ref: '#/components/schemas/auth.CreateSessionResponse' '201': description: New pending session created; visit verification_url to complete. content: application/json: schema: $ref: '#/components/schemas/auth.CreateSessionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/auth.errorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/auth.errorResponse' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/auth.errorResponse' security: - API_Key: [] - Tenant_ID: [] - Bearer_Auth: [] components: schemas: auth.CreateSessionRequest: type: object properties: is_default: description: >- Defaults to true. When adding a secondary account (strategy: CREATE), set false. type: boolean provider_slug: type: string redirect_uri: description: >- Custom OAuth callback URL for headless flows. Must be a member of the provider's allowed_redirect_uris allowlist (enforced by host-backend); forwarded as-is. type: string scopes: type: array items: type: string strategy: type: string enum: - REUSE - CREATE token_id: description: >- Target a specific stored token in multi-account flows; must belong to the caller. type: string auth.CreateSessionResponse: type: object properties: id: type: string metadata: type: object additionalProperties: {} provider_slug: type: string status: $ref: '#/components/schemas/auth.SessionStatus' token: type: string verification_url: type: string auth.errorResponse: type: object properties: code: type: string detail: type: string status: type: integer type: type: string auth.SessionStatus: type: string enum: - PENDING - COMPLETED - CONNECTION_REQUIRED - TOKEN_EXPIRED x-enum-varnames: - SessionStatusPending - SessionStatusCompleted - SessionStatusConnectionRequired - SessionStatusTokenExpired securitySchemes: API_Key: description: LangSmith API key (`lsv2_...`). type: apiKey name: X-Api-Key in: header Tenant_ID: description: Workspace (tenant) UUID the request operates in. type: apiKey name: X-Tenant-Id in: header Bearer_Auth: description: Session JWT, sent as `Bearer `. type: apiKey name: Authorization in: header ````