> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Share Session

> Mint a short-lived JWT that lets a specific Didit application import this finished session. Pair with `POST /v3/session/import-shared/`.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Share Session Prompt"
  prompt={`Mint a short-lived share token so another Didit application can import this finished verification session (Reusable KYC / KYB).

Endpoint:
POST https://verification.didit.me/v3/session/{session_id}/share/

Authentication:
Use the x-api-key header with your Didit API key. Privilege: write:sessions.

Path parameter:
- session_id (UUID) — works for both User Verification (KYC) and Business Verification (KYB).

Request body:
- for_application_id (string, UUID, required) — UUID of the receiving Didit application. Must exist, must not be soft-deleted, and must be different from the calling application.
- ttl_in_seconds (integer, optional, default 3600) — Lifetime of the share token. Min 60, max 86400 (24 hours).

Prerequisites:
- Session status must be one of "Approved", "Declined", "In Review". Any other status returns 400 ("Only finished sessions ... can be shared.").

curl example:
curl -X POST https://verification.didit.me/v3/session/<SESSION_ID>/share/ \\
-H "x-api-key: <API_KEY>" \\
-H "Content-Type: application/json" \\
-d '{
"for_application_id": "<PARTNER_APP_UUID>",
"ttl_in_seconds": 3600
}'

Response:
- share_token (string) — HS256-signed JWT with payload { session_id, session_kind, from_application_id, for_application_id, iat, exp }.
- for_application_id (UUID) — echoed back.
- session_kind ("user" | "business") — embedded so the receiver clones the right kind.

Token characteristics:
- Bound to for_application_id — only that application can redeem it via POST /v3/session/import-shared/.
- Cannot be revoked via API — it simply expires after ttl_in_seconds.
- You can mint multiple tokens for the same session (e.g. one per partner). Each call returns a fresh JWT with a new iat.

Failure modes:
- 400 — { "detail": "Only finished sessions ... can be shared." } when the session isn't Approved/Declined/In Review.
- 400 — { "for_application_id": ["..."] } for unknown or self application UUIDs.
- 401 — invalid API key.
- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
- 404 — { "detail": "Not found." } when the session_id is not visible to this application.

Send the share_token to the receiving partner through your own secure channel (HTTPS API call, webhook, signed email link, etc.).

Next step:
The receiving application calls POST https://verification.didit.me/v3/session/import-shared/ with the share_token to clone the session — see /sessions-api/share-session/import.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. Didit looks up the `session_id` in both tables and generates a JWT share token that includes:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user" | "business",
  "from_application_id": "...",
  "for_application_id": "...",
  "iat": ...,
  "exp": ...
}
```

When the receiving partner imports the token, Didit clones the corresponding kind of session (KYC or KYB) with its relations.

## Requirements

* Session must be in a **finished** status (`APPROVED`, `DECLINED`, `IN_REVIEW`).
* You must have the `write:sessions` privilege.
* The `for_application_id` must be a valid Didit application (usually a partner's application).

## Examples

<Tabs>
  <Tab title="Share a User Verification (KYC) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/4c5c7f3a-.../share/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "for_application_id": "partner-app-uuid",
        "ttl_in_seconds": 3600
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "for_application_id": "partner-app-uuid",
      "session_kind": "user"
    }
    ```
  </Tab>

  <Tab title="Share a Business Verification (KYB) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/bs-01HJX1.../share/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "for_application_id": "partner-app-uuid",
        "ttl_in_seconds": 7200
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "for_application_id": "partner-app-uuid",
      "session_kind": "business"
    }
    ```
  </Tab>
</Tabs>

## TTL bounds

| Parameter        | Min | Max   | Default |
| ---------------- | --- | ----- | ------- |
| `ttl_in_seconds` | 60  | 86400 | 3600    |

## Related

* [Import shared session](/sessions-api/share-session/import)
* [Reusable KYC guide](/core-technology/reusable-kyc/share-kyc-via-api)
* [Sessions overview](/sessions-api/overview)


## OpenAPI

````yaml POST /v3/session/{sessionId}/share/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/share/:
    post:
      tags:
        - Sessions
      summary: Mint a share token for a finished verification session
      description: >-
        Mint a short-lived JWT that lets a specific Didit application import
        this finished session. Pair with `POST /v3/session/import-shared/`.
      operationId: post_v3_session_share
      parameters:
        - in: path
          name: sessionId
          required: true
          description: UUID of the source verification session to mint a token for.
          schema:
            type: string
            format: uuid
            example: 11111111-2222-3333-4444-555555555555
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - for_application_id
              properties:
                for_application_id:
                  type: string
                  format: uuid
                  description: >-
                    UUID of the Didit application that will redeem the token.
                    Must exist, must not be soft-deleted, and must differ from
                    the calling application. Find it in the Business Console
                    under **Settings → Application**.
                  example: a5f3bca2-46e2-411e-90ef-a580900a57ee
                ttl_in_seconds:
                  type: integer
                  description: >-
                    Token lifetime, in seconds. Minimum `60`, maximum `86400`
                    (24 h). Defaults to `3600` (1 h).
                  minimum: 60
                  maximum: 86400
                  default: 3600
                  example: 3600
            example:
              for_application_id: a5f3bca2-46e2-411e-90ef-a580900a57ee
              ttl_in_seconds: 7200
      responses:
        '200':
          description: Share token minted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  share_token:
                    type: string
                    description: >-
                      HS256-signed JWT. Pass this verbatim as `share_token` to
                      [`POST
                      /v3/session/import-shared/`](/sessions-api/import-shared-session)
                      on the target application.
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  for_application_id:
                    type: string
                    format: uuid
                    description: >-
                      Echoes the target application UUID that the token is bound
                      to.
                    example: a5f3bca2-46e2-411e-90ef-a580900a57ee
                  session_kind:
                    type: string
                    enum:
                      - user
                      - business
                    description: >-
                      Whether the source session is a User Verification (KYC) or
                      Business Verification (KYB) session.
              examples:
                User session:
                  summary: Share a KYC session
                  value:
                    share_token: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMjBiYjNjM2ItNjE0Ni00MzlmLTg0YTQtYmQzMGQwMGFjNmEyIiwiZnJvbV9hcHBsaWNhdGlvbl9pZCI6ImRiZDIwZTM0LTQyZTktNGYyYy1iYTkxLWNmMDc2MjAxNmY2NCIsImZvcl9hcHBsaWNhdGlvbl9pZCI6ImE1ZjNiY2EyLTQ2ZTItNDExZS05MGVmLWE1ODA5MDBhNTdlZSIsImlhdCI6MTc1MzYzMDY2NiwiZXhwIjoxNzUzNjM0MjY2fQ.JJ9pNE_hqZsOtbR0XYZIWw4JzidjdEl279iUrsIkhGE
                    for_application_id: a5f3bca2-46e2-411e-90ef-a580900a57ee
                    session_kind: user
                Business session:
                  summary: Share a KYB session
                  value:
                    share_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                    for_application_id: a5f3bca2-46e2-411e-90ef-a580900a57ee
                    session_kind: business
        '400':
          description: >-
            Validation error. Field errors are keyed by field name; the
            not-finished error arrives under a `detail` key (as an array).
          content:
            application/json:
              examples:
                Wrong status:
                  summary: Source session is not finished
                  value:
                    detail:
                      - >-
                        Only finished sessions ("Approved", "Declined", "In
                        Review") can be shared.
                Target missing:
                  summary: Target application does not exist
                  value:
                    for_application_id:
                      - Target application does not exist.
                Self-share:
                  summary: Target is the calling application
                  value:
                    for_application_id:
                      - Cannot share a session with the same application.
                TTL bounds:
                  summary: ttl_in_seconds outside bounds
                  value:
                    ttl_in_seconds:
                      - Ensure this value is greater than or equal to 60.
        '401':
          description: >-
            Missing or invalid credentials. Unlike most v3 endpoints, this
            endpoint authenticates through the permission decorator and returns
            `401` when no valid token/key is presented.
          content:
            application/json:
              examples:
                Unauthorized:
                  summary: Unauthorized
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
        '403':
          description: >-
            The credentials are valid but lack the `write:sessions` permission
            for this application.
          content:
            application/json:
              examples:
                No Permission:
                  summary: No Permission
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: No session with the given `session_id` exists in your application.
          content:
            application/json:
              examples:
                Not Found:
                  summary: Session not found
                  value:
                    detail: Not found.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST \
              https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee",
                "ttl_in_seconds": 7200
              }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                "https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/",
                headers={
                    'x-api-key': 'YOUR_API_KEY',
                    "Content-Type": "application/json",
                },
                json={
                    "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee",
                    "ttl_in_seconds": 7200,
                },
            )
            response.raise_for_status()
            share_token = response.json()["share_token"]
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/',
              {
                method: 'POST',
                headers: {
                  'x-api-key': 'YOUR_API_KEY',
                  'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                  for_application_id: 'a5f3bca2-46e2-411e-90ef-a580900a57ee',
                  ttl_in_seconds: 7200,
                }),
              },
            );
            if (!response.ok) throw new Error(`HTTP ${response.status}`);
            const { share_token } = await response.json();
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````