Saltar para o conteúdo principal
POST
Criar Sessão

Criar Sessão

POST /v1/agent-sessions Cria uma nova sessão autenticada para um agente de máquina. A sessão vincula um token de acesso com tempo limitado e um token de atualização ao agente, com um conjunto de escopo explícito que deve ser um subconjunto dos escopos concedidos ao agente. Os token e refresh_token são retornados apenas na resposta de criação. Armazene-os com segurança — eles não podem ser recuperados posteriormente.
Os campos token e refresh_token são retornados apenas uma vez nesta resposta. Armazene-os em um gerenciador de segredos seguro ou armazenamento criptografado imediatamente. Se perdido, encerre a sessão e crie uma nova.

Autenticação

Requer cabeçalho X-API-Key ou token JWT de portador. O espaço de trabalho é derivado da credencial autenticada; não envie X-Tenant-ID.

Resposta

object
O objeto de sessão criado contendo:
string
Chave primária UUID interna.
string
Identificador de sessão MAIP no formato maip-sess:<short-uuid>:<random-hex>. Use este ID em chamadas de API subsequentes.
string
O agente ao qual esta sessão pertence.
string
Status da sessão. Sempre "active" na criação.
string[]
Os escopos efetivos para esta sessão.
object
Metadados da sessão.
string
Carimbo de data/hora de expiração ISO 8601.
string
Carimbo de data/hora de criação ISO 8601.
string
Carimbo de data/hora da última atualização ISO 8601.
string
Token de acesso opaco para autenticar solicitações de API dentro desta sessão. String hexadecimal de 64 caracteres. Retornada apenas uma vez.
string
Token para atualizar a sessão antes do vencimento. String hexadecimal de 64 caracteres. Retornado apenas uma vez.

Exemplo


Ciclo de Vida da Sessão

Um recibo de sessão é criado automaticamente quando a sessão começa, vinculando a sessão à trilha de auditoria do agente.

Autorizações

X-API-Key
string
header
obrigatório

Chave de API para autenticação máquina a máquina

Corpo

application/json
agent_id
string<uuid>
obrigatório

Agente para criar a sessão para

metadata
any
scopes
string[]

Escopos para esta sessão (deve ser um subconjunto dos escopos do agente)

ttl_minutes
integer

Resposta

Sessão criada

session_id
string<uuid>
agent_id
string<uuid>
token
string

Token de portador da sessão (retornado uma vez na criação)

scopes
string[]
status
enum<string>
Opções disponíveis:
active,
terminated,
expired
metadata
object
expires_at
string<date-time>
created_at
string<date-time>
terminated_at
string<date-time>