> ## 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.

# API de Partilha de Sessão: Gerar Token de Partilha

> Didit: gere um token de partilha temporário com POST /v3/session/{id}/share/ para KYC ou KYB reutilizável. JWT, pago por chamada, sem contratos.



Prompt de Partilha de Sessão
        Copiar o prompt para a área de transferência



      
      

\<pre>

\`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 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.`

\</pre>



      
      

Colar em

## Suporte a KYC e KYBFunciona tanto para sessões de **Verificação de utilizadores (KYC)** como de **Verificação de empresas (KYB)**. A Didit procura o `session_id` em ambos os tipos de sessão e gera um token de partilha JWT que inclui:```json theme={null}
{
  "session_id": "...",
  "session_kind": "user" | "business",
  "from_application_id": "...",
  "for_application_id": "...",
  "iat": ...,
  "exp": ...
}
```Quando o parceiro destinatário importa o token, a Didit clona a sessão do tipo correspondente (KYC ou KYB) com as respetivas relações.## Requisitos- A sessão tem de estar num estado **concluído** (`APPROVED`, `DECLINED`, `IN_REVIEW`).
- Tem de ter o privilégio `write:sessions`.
- O `for_application_id` tem de ser uma aplicação Didit válida (normalmente a aplicação de um parceiro).## Exemplos> [tab] Partilhar uma sessão de Verificação de utilizadores (KYC)
>
> ```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
>   }'
> ```
>
> **Resposta:**
>
> ```json theme={null}
> {
>   "share_token": "eyJhbGciOiJIUzI1NiJ9...",
>   "for_application_id": "partner-app-uuid",
>   "session_kind": "user"
> }
> ```> [tab] Partilhar uma sessão de Verificação de empresas (KYB)
>
> ```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
>   }'
> ```
>
> **Resposta:**
>
> ```json theme={null}
> {
>   "share_token": "eyJhbGciOiJIUzI1NiJ9...",
>   "for_application_id": "partner-app-uuid",
>   "session_kind": "business"
> }
> ```## Limites do TTL| Parâmetro | Mínimo | Máximo | Predefinição |
| - | - | - | - |
| `ttl_in_seconds` | 60 | 86400 | 3600 |## Relacionados- [Importar sessão partilhada](https://docs.didit.me/pt/sessions-api/share-session/import.md)
- [Guia de KYC reutilizável](https://docs.didit.me/pt/core-technology/reusable-kyc/share-kyc-via-api.md)
- [Visão geral das sessões](https://docs.didit.me/pt/sessions-api/overview.md)


## OpenAPI

````yaml pt/openapi-25.json POST /v3/session/{sessionId}/share/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/share/:
    post:
      tags:
        - Sessions
      summary: Gerar um token de partilha para uma sessão de verificação concluída
      description: >-
        Gerar um JWT de curta duração que permite a uma aplicação Didit
        específica importar esta sessão concluída. Combine com `POST
        /v3/session/import-shared/`.
      operationId: post_v3_session_share
      parameters:
        - in: path
          name: sessionId
          required: true
          description: UUID da sessão de verificação de origem para a qual gerar um token.
          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 da aplicação Didit que irá resgatar o token. Deve
                    existir, não pode estar eliminada e tem de ser diferente da
                    aplicação que efetuou a chamada. Encontre-o na Business
                    Console em **Definições → Aplicação**.
                  example: a5f3bca2-46e2-411e-90ef-a580900a57ee
                ttl_in_seconds:
                  type: integer
                  description: >-
                    Tempo de vida útil do token, em segundos. Mínimo `60`,
                    máximo `86400` (24 h). O valor predefinido é `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: Token de partilha gerado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  share_token:
                    type: string
                    description: >-
                      JWT assinado com HS256. Passe este valor textualmente como
                      `share_token` para [`POST
                      /v3/session/import-shared/`](/sessions-api/import-shared-session)
                      na aplicação de destino.
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  for_application_id:
                    type: string
                    format: uuid
                    description: >-
                      Repete o UUID da aplicação de destino à qual o token está
                      vinculado.
                    example: a5f3bca2-46e2-411e-90ef-a580900a57ee
                  session_kind:
                    type: string
                    enum:
                      - user
                      - business
                    description: >-
                      Se a sessão de origem é uma sessão de Verificação de
                      utilizadores (KYC) ou de Verificação de empresas (KYB).
              examples:
                User session:
                  summary: Partilhar uma sessão de KYC
                  value:
                    share_token: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMjBiYjNjM2ItNjE0Ni00MzlmLTg0YTQtYmQzMGQwMGFjNmEyIiwiZnJvbV9hcHBsaWNhdGlvbl9pZCI6ImRiZDIwZTM0LTQyZTktNGYyYy1iYTkxLWNmMDc2MjAxNmY2NCIsImZvcl9hcHBsaWNhdGlvbl9pZCI6ImE1ZjNiY2EyLTQ2ZTItNDExZS05MGVmLWE1ODA5MDBhNTdlZSIsImlhdCI6MTc1MzYzMDY2NiwiZXhwIjoxNzUzNjM0MjY2fQ.JJ9pNE_hqZsOtbR0XYZIWw4JzidjdEl279iUrsIkhGE
                    for_application_id: a5f3bca2-46e2-411e-90ef-a580900a57ee
                    session_kind: user
                Business session:
                  summary: Partilhar uma sessão de KYB
                  value:
                    share_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                    for_application_id: a5f3bca2-46e2-411e-90ef-a580900a57ee
                    session_kind: business
        '400':
          description: >-
            Erro de validação. Os erros de campo são indexados pelo nome do
            campo; o erro de não concluído surge sob a chave `detail` (como um
            array).
          content:
            application/json:
              examples:
                Wrong status:
                  summary: A sessão de origem não está finalizada
                  value:
                    detail:
                      - >-
                        Only finished sessions ("Approved", "Declined", "In
                        Review") can be shared.
                Target missing:
                  summary: A aplicação de destino não existe
                  value:
                    for_application_id:
                      - Target application does not exist.
                Self-share:
                  summary: O destino é a aplicação chamadora
                  value:
                    for_application_id:
                      - Cannot share a session with the same application.
                TTL bounds:
                  summary: ttl_in_seconds fora dos limites
                  value:
                    ttl_in_seconds:
                      - Ensure this value is greater than or equal to 60.
        '401':
          description: >-
            Credenciais em falta ou inválidas. Ao contrário da maioria dos
            endpoints v3, este endpoint autentica através do decorador de
            permissões e devolve `401` quando nenhum token/chave válido é
            apresentado.
          content:
            application/json:
              examples:
                Unauthorized:
                  summary: Não autorizado
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
        '403':
          description: >-
            As credenciais são válidas, mas não possuem a permissão
            `write:sessions` para esta aplicação.
          content:
            application/json:
              examples:
                No Permission:
                  summary: Sem permissão
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: >-
            Não existe nenhuma sessão com o `session_id` fornecido na sua
            aplicação.
          content:
            application/json:
              examples:
                Not Found:
                  summary: Sessão não encontrada
                  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: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.sessions.share(
                "11111111-2222-3333-4444-555555555555",
                for_application_id="a5f3bca2-46e2-411e-90ef-a580900a57ee",
                ttl_in_seconds=7200,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.sessions.share("11111111-2222-3333-4444-555555555555", {
              for_application_id: "a5f3bca2-46e2-411e-90ef-a580900a57ee",
              ttl_in_seconds: 7200,
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Share(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsShareParams{\n\tForApplicationID: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n\tTTLInSeconds:     didit.Int(7200),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.SessionsShareParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.sessions().share("11111111-2222-3333-4444-555555555555",
            SessionsShareParams.builder()
                    .forApplicationId("a5f3bca2-46e2-411e-90ef-a580900a57ee")
                    .ttlInSeconds(7200L)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->sessions->share('11111111-2222-3333-4444-555555555555', [
                'for_application_id' => 'a5f3bca2-46e2-411e-90ef-a580900a57ee',
                'ttl_in_seconds' => 7200,
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.sessions.share(
              "11111111-2222-3333-4444-555555555555",
              for_application_id: "a5f3bca2-46e2-411e-90ef-a580900a57ee",
              ttl_in_seconds: 7200
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Sessions.ShareAsync("11111111-2222-3333-4444-555555555555",
            new SessionsShareParams

            {
                ForApplicationId = "a5f3bca2-46e2-411e-90ef-a580900a57ee",
                TtlInSeconds = 7200,
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        A chave de API da sua aplicação, a partir de Programadores -> Chaves de
        API na Business Console. A chave principal tem acesso total. Uma chave
        nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por
        recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de
        endereços IP e a uma data de validade. 401 significa que a chave está
        incorreta, revogada ou expirada; 403 significa que nenhuma chave foi
        enviada, que a chave não tem acesso a este recurso ou ação, ou que o
        pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
        sessão significa que a sessão está fora dos fluxos ou estados da chave.
        Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs
        como nulos, e uma chave sem permissão de escrita em sessões recebe
        ligações de sessão e tokens como nulos. Consulte
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.