> ## 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. # Mint a subject_token > A token of up to 15 minutes that binds an MCP connection to one customer, and to their account when there is one. ## OpenAPI ````yaml openapi/en/cell.json POST /v1/subject-tokens openapi: 3.1.0 info: title: Niadra data API version: '1' description: >- Writing, context, history, objects, identity, privacy and governance of one space. Every space has a stable address, with the space and the region in its name. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: The space, which comes in the source key. region: default: us-east-1 description: The region of the space, which also comes in the key. security: [] paths: /v1/subject-tokens: post: tags: - read summary: Mint a subject_token description: >- Your backend mints a token that binds an MCP connection to one customer, one conversation and one verification level, for up to 15 minutes. Send it in the `Niadra-Subject-Token` header when the agent opens the MCP connection, next to the source key. The model never sees or chooses the customer, and the handle travels sealed inside the token. **Authentication.** Source key: `Authorization: Bearer nia_sk_...`. Required scope: `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: The token. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The request does not match the contract. 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: >- The organization the customer acts for, bound like the subject: tools use it and the model cannot change it. Every read still checks the link. 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: The level the conversation claims; never above the source's ceiling. required: - subject title: SubjectTokenRequest type: object description: >- Minted by your backend with its source key. The handle travels sealed inside the token. SubjectTokenResponse: additionalProperties: false properties: expires_at: format: date-time title: Expires At type: string description: 15 minutes after minting. token: description: >- Signed, valid for 15 minutes; send it as `Niadra-Subject-Token` to /mcp. title: Token type: string required: - token - expires_at title: SubjectTokenResponse type: object Problem: additionalProperties: false description: RFC 9457 problem details; `code` comes from the versioned error catalog. 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: >- An identifier of a subject in some channel or system: a phone, an e-mail, a CRM id. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Namespace for scoped identifiers: the WhatsApp Business account for `wa_bsuid`, the system for `system_id`, the country for `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: Defaults to `person`, except for organization-only handle types. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- The identifier. Normalized on the server: E.164 for phones, lowercase for e-mail. required: - type - value title: Handle type: object Verification: description: Session verification levels. `no_customer` sits outside the V0-V4 scale. enum: - V0 - V1 - V2 - V3 - V4 - no_customer title: Verification type: string SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- A person, a customer organization (`account`) or an organization that takes part without being a customer (`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: >- The kind of identifier. The value is classified by its format, never by the field it came from. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````