> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Emitir subject_token > Um token de até 15 minutos que amarra uma conexão MCP a um cliente, e à conta dele quando houver. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/subject-tokens openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-1 description: A região do espaço, que também vem na chave. security: [] paths: /v1/subject-tokens: post: tags: - read summary: Emitir subject_token description: >- O seu backend emite um token que amarra uma conexão MCP a um cliente, a uma conversa e a um nível de verificação, por até 15 minutos. Envie no cabeçalho `Niadra-Subject-Token` quando o agente abrir a conexão MCP, junto da chave da fonte. O modelo nunca vê nem escolhe o cliente, e o handle viaja lacrado dentro do token. **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`. Escopo exigido: `context`. operationId: subject_token_v1_subject_tokens_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SubjectTokenRequest' example: subject: type: phone_e164 value: '+14155550123' verification: V1 conversation_id: call-4471 required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SubjectTokenResponse' example: token: nst1.eyJleHAiOjE3NTg1NjIxMjN9.Q2sX... expires_at: '2026-09-22T17:22:03Z' description: O token. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- 422 `invalid_input`, `verification_not_allowed` ou `about_without_link`. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: |- token = niadra.subject_token( phone("+14155550123"), verification="V1", conversation_id="call-4471", ) # Open the MCP connection to niadra.mcp_url with the source key # and token.headers ({"Niadra-Subject-Token": ...}) - lang: typescript label: TypeScript source: |- const { data: token } = await niadra.subjectToken({ subject: handles.phone("+14155550123"), verification: "V1", conversation_id: "call-4471", }); // Open the MCP connection with the source key and the // "Niadra-Subject-Token" header set to token.token components: schemas: SubjectTokenRequest: additionalProperties: false properties: about: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' description: A conta ou o parceiro em nome de quem a pessoa age. conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id subject: $ref: '#/components/schemas/Handle' task_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Task Id verification: $ref: '#/components/schemas/Verification' default: V0 description: O nível provado nesta conversa. Limitado pelo teto da fonte. required: - subject title: SubjectTokenRequest type: object description: >- Emitido pelo seu backend com a chave da fonte. O handle viaja lacrado dentro do token. SubjectTokenResponse: additionalProperties: false properties: expires_at: format: date-time title: Expires At type: string description: 15 minutos depois da emissão. token: description: Token opaco que começa com `nst1.`. title: Token type: string required: - token - expires_at title: SubjectTokenResponse type: object Problem: additionalProperties: false description: >- Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de erros versionado. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object Handle: additionalProperties: false description: >- Um identificador de um sujeito num canal ou sistema: um telefone, um e-mail, um id do CRM. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Espaço de nomes dos identificadores com escopo: a conta do WhatsApp Business para `wa_bsuid`, o sistema para `system_id`, o país para `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: >- O padrão é `person`, exceto nos tipos de handle que só identificam organizações. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- O identificador. Normalizado no servidor: E.164 para telefone, minúsculas para e-mail. required: - type - value title: Handle type: object Verification: description: >- Nível de verificação da sessão. V0 autodeclarado, V1 plausível pelo canal, V2 atestado pelo canal, V3 desafiado (OTP ou login), V4 conferido com um sistema de registro ou por um atendente. `no_customer` vale para tarefas sem cliente presente e só é aceito de fontes de agente interno. enum: - V0 - V1 - V2 - V3 - V4 - no_customer title: Verification type: string SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- Uma pessoa, uma organização cliente (`account`) ou uma organização que participa sem ser cliente (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- O tipo de identificador. O valor é classificado pelo formato, nunca pelo campo de onde veio. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````