---
title: "Request a credential (agent)"
method: POST
path: "/v1/credentials/request"
tags: ["credentials"]
---

# Request a credential (agent)

`POST /v1/credentials/request`

## Request

- Base URL: `https://agentlair.dev`
- URL: `https://agentlair.dev/v1/credentials/request`
- Auth: HTTP bearer

Initiates a credential device flow. The agent provides the type and service name, and receives a `device_code` + `user_code`. The user code must be shown to the operator (or sent via email, which AgentLair handles automatically). The agent then polls `/v1/credentials/poll` until the credential is delivered or the request expires (5 minutes).

## Request body

- object
  - `credential_type` 'api_key' | 'password' | 'token' | 'certificate', required: Type of credential being requested
  - `service_name` string, required: Name of the service the credential is for
  - `description` string: Optional human-readable description of why the credential is needed

## Response `201`

Credential request created

- object
  - `device_code` string: Opaque device code used for polling. Keep secret.
  - `user_code` string: Short human-readable code shown to the operator. Format: XXXX-XXXX.
  - `expires_in` integer: Seconds until the request expires
  - `interval` integer: Recommended polling interval in seconds
  - `message` string: Human-readable instruction for the agent

## Other responses

- `400`: Invalid request body
- `401`: Authentication required
- `429`: Too many active credential requests (max 5 per account)

---

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