> ## 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. # Consultar sessão | API de Autenticação da Didit > O GET /session/ da Didit valida um token de acesso na sessão ativa e falha na hora após revogação, inatividade, bloqueio ou renovação. > [!WARNING] > > A autenticação é um recurso novo. Esses endpoints são disponibilizados pelo emissor da sua aplicação, como `https://.auth.didit.me`, e nunca aceitam a sua chave de API da Didit. Esta é a verificação instantânea de revogação. São permitidas 30 requisições por minuto e 300 por hora por endereço IP, então verifique os tokens offline em todas as requisições e chame-a antes de ações sensíveis. Consulte [Verificar a sessão](https://docs.didit.me/pt-br/authentication/tokens-and-jwks.md#verificar-a-sessão). ## OpenAPI ````yaml pt-br/openapi-authentication.json GET /session/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- Os endpoints voltados ao servidor do Didit Authentication, o produto de login para os usuários finais da sua aplicação. O Authentication é **novo** e chega à produção na versão de 2026-11-01. ## URL base Cada aplicação é o seu próprio emissor OpenID Connect, e todos os endpoints abaixo são servidos na raiz desse emissor: - `https://.auth.didit.me` para uma aplicação de produção, ou `https://.sandbox.auth.didit.me` para uma aplicação de sandbox. - O seu próprio domínio personalizado, depois de ativado. Ele passa então a substituir o host padrão como emissor: novos tokens o indicam em `iss`, o discovery aponta para ele e a chave publicável muda. Tokens de acesso emitidos sob o host padrão falham em `/session/`, `/step-up/` e `/monitoring-token/` até serem renovados. Produção e sandbox são aplicações separadas, portanto são emissores separados, com chaves separadas. A chave publicável é `pk_live_` (produção) ou `pk_test_` (sandbox) seguida da codificação base64url sem preenchimento do emissor, sem barra final: decodifique-a para descobrir o emissor. Ela é um identificador público, não uma credencial. Os mesmos endpoints JSON também são servidos em `https://apx.didit.me/auth/v2/authentication/{application_id}/`. Os tokens sempre indicam o emissor acima, seja qual for o endereço que os emitiu. ## Credenciais Estes endpoints nunca recebem a sua chave de API do Didit nem um token do console. - O discovery, o JWKS e `POST /token/` não recebem credencial. Os clientes são públicos: não há client secret, e um código de autorização fica vinculado ao seu verificador PKCE (`S256`). O `client_id` é o ID da sua aplicação. - `/session/`, `/step-up/` e `/monitoring-token/` recebem o token de acesso da pessoa: `Authorization: Bearer `. Cada chamada bem-sucedida conta como atividade na sessão, então reinicia o tempo limite de inatividade da sessão. ## Corpos de requisição Todo endpoint que recebe um corpo aceita corpos JSON, form-encoded e multipart. Este documento lista JSON, além de form-encoded para `POST /token/`, como os clientes OAuth o enviam. Um campo que o endpoint não aceita recebe `400 {"": "unknown_field"}`. ## Tokens - **Token de acesso**: um JWT ES256 com o cabeçalho `typ: at+jwt`, válido por no máximo 5 minutos e nunca por mais tempo que a sua sessão. Claims: `AccessTokenClaims`. - **ID token**: um JWT ES256 com o cabeçalho `typ: JWT`. Claims: `IDTokenClaims`. Ele nunca é aceito como token de acesso. - **Refresh token**: uma string aleatória que é rotacionada a cada uso. Enviar novamente um refresh token já usado revoga a sessão. Verifique um token com as chaves de `GET /.well-known/jwks.json`: o algoritmo deve ser `ES256`, `typ` deve corresponder ao tipo de token, `iss` deve ser igual ao emissor que você configurou e `aud` ao ID da sua aplicação. A verificação offline só percebe uma sessão revogada quando o token de acesso dela expira; `GET /session/` é a verificação instantânea. ## Erros | Corpo | Quando | | --- | --- | | `{"error": ""}` | Erros de `POST /token/`, todos com status `400`, no formato de corpo da [RFC 6749, seção 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client` e o `mfa_required` do Didit. Erros de serviço: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` ou `{"": ""}` | Um campo da requisição falhou na validação. `non_field_errors` indica uma regra que envolve vários campos, e `unknown_field`, um campo que o endpoint não aceita. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (aplicação ou step-up desconhecidos) e `429` (limite de requisições). Também `400` para um corpo que não pode ser interpretado (`JSON parse error - ...`), `405` para um método que o endpoint não atende e `415` para um `Content-Type` não suportado. | Um `401` também traz `WWW-Authenticate: Bearer`, e um `429` traz `Retry-After` em segundos. Duas recusas não são JSON. Um endereço que não é um emissor é recusado antes de chegar a estes endpoints, por exemplo com um `404` vazio para um nome `*.auth.didit.me` não utilizado. Um `step_up_id` que não é um UUID recebe uma página `404`. ## Limites de requisições Uma requisição precisa passar por duas camadas. **Limites por endpoint**, contados por endereço IP do cliente, por aplicação e por endpoint: - Discovery e JWKS: 1.200 requisições por minuto e 12.000 por hora. - Todos os demais endpoints: 30 requisições por minuto e 300 por hora. `GET` e `DELETE /session/` compartilham a mesma contagem. Acima de um limite: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, ou `3600 seconds` para o limite por hora. **Proteção contra bots**, em todo `POST` e `DELETE`. Seus buckets são compartilhados por todas as requisições `POST` e `DELETE` da aplicação, incluindo as etapas de login hospedadas, e são reabastecidos continuamente: - 60 requisições por minuto por endereço IP do cliente. - 30 requisições por minuto por dispositivo, para requisições que identificam o seu dispositivo, como fazem os SDKs de navegador e nativos. - 1.000 requisições por minuto para a aplicação inteira, somando todos os endereços IP. Acima de um bucket: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` quando N é 1). O bucket por IP abrange vários endpoints, então um único endereço que mistura chamadas de token, step-up e logout pode esgotá-lo antes de atingir qualquer limite por endpoint. O bucket da aplicação conta todos os clientes da aplicação, incluindo navegadores. As duas camadas respondem antes de o endpoint ser executado, então uma requisição que recebeu `429` não foi executada: tente novamente depois de `Retry-After`, inclusive no caso de uma renovação. ## Requisições do navegador Uma requisição que traz um cabeçalho `Origin` deve vir de uma das origens da própria aplicação ou de suas origens permitidas; caso contrário, recebe `403 origin_not_allowed`. Requisições de servidor para servidor não enviam `Origin`. ## Fora do escopo deste documento Estas rotas atendem às páginas hospedadas, aos SDKs de navegador e nativos e a agentes de IA. Elas não fazem parte do contrato de servidor, e os SDKs de servidor não as chamam: - Etapas de login: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*` e `/protection/complete/`. - Páginas hospedadas e callbacks: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/` e os arquivos de associação de apps nativos em `/.well-known/`. - Acesso de agentes: `/agents/*` e `/grants/`, incluindo `GET /agents/session/`, a verificação em tempo real do token de acesso de um agente de IA. O acesso de agentes não faz parte desta versão do contrato. - A API de gerenciamento do console para o Authentication, que recebe sessões do console. Os eventos do Authentication ainda não são entregues como webhooks, por isso este documento não define nenhum webhook. servers: - url: https://{issuer} description: 'O emissor da sua aplicação: a origem do login.' variables: issuer: default: your-app.auth.didit.me description: >- O host do emissor: `.auth.didit.me` (produção), `.sandbox.auth.didit.me` (sandbox) ou o seu domínio personalizado ativo. security: [] tags: - name: Issuer description: Chaves de descoberta e de assinatura, para verificar tokens. - name: Tokens description: Os grants de código de autorização e de refresh. - name: Sessions description: Verifica e encerra a sessão vinculada a um token de acesso. - name: Step-ups description: Verificação antes de uma ação sensível. - name: Monitoring description: Credenciais do dispositivo para eventos de monitoramento de transações. paths: /session/: get: tags: - Sessions summary: Obter a sessão description: >- Verifica o token de acesso em relação à sessão ativa e o retorna. É mais rigoroso do que verificar o JWT por conta própria: também falha imediatamente quando a sessão foi revogada, ficou inativa ou ultrapassou seu tempo de vida, quando a pessoa foi bloqueada ou seu e-mail deixou de estar verificado, quando a sessão não atende mais à sua política de MFA (por exemplo, depois que a pessoa adicionou um app autenticador ou se tornou administradora da organização), ou quando o token foi substituído por uma renovação. Use-o antes de uma ação sensível, por exemplo um pagamento. Uma verificação bem-sucedida conta como atividade, então reinicia o tempo limite de inatividade da sessão. operationId: authentication_get_session responses: '200': description: A sessão é do ambiente de produção. headers: Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Session' examples: Session: summary: Uma sessão com senha value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - password mfa_verified: false email: person@example.com email_verified: true phone: null verified_identity: null verified: null expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: '' organizations: [] VerifiedMember: summary: Um membro verificado da organização value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - passkey mfa_verified: true email: person@example.com email_verified: true phone: '+34600000000' verified_identity: null verified: level: full_id over_18: true given_name: Alex country: ES expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: https://app.example.com/ organizations: - organization_id: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: Northwind role: admin custom_role: null '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: Session: type: object description: A sessão ativa por trás de um token de acesso. required: - sub - sid - application_id - vendor_data - amr - mfa_verified - email - email_verified - phone - verified_identity - verified - expires_at - post_logout_redirect_uri - organizations properties: sub: type: string format: uuid description: O ID da identidade. example: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: type: string format: uuid description: O ID da sessão. example: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: type: string format: uuid example: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: type: string description: >- A referência da pessoa em todos os produtos da Didit, como nos tokens. example: user-42 amr: $ref: '#/components/schemas/AuthenticationMethods' mfa_verified: type: boolean description: >- Se a sessão passou por um segundo fator. Sempre `true` para um login com passkey. example: false email: type: string format: email nullable: true example: person@example.com email_verified: type: boolean example: true phone: type: string nullable: true description: Número de telefone no formato E.164, ou `null`. example: null verified_identity: $ref: '#/components/schemas/WalletVerification' verified: type: object nullable: true description: >- Nível de verificação e claims selecionadas, o mesmo objeto que os tokens contêm como `verified`, ou `null` quando não houver nenhum. Consulte este campo, e não `email_verified`, para saber se a pessoa verificou a identidade. properties: level: type: string enum: - liveness - liveness_face_match - full_id description: >- O nível mais alto aprovado. Do mais fraco ao mais forte: `liveness`, `liveness_face_match`, `full_id`. example: full_id over_18: type: boolean example: true over_21: type: boolean example: true given_name: type: string example: Alex family_name: type: string example: Doe birthdate: type: string description: Data de nascimento do documento, `YYYY-MM-DD`. example: '1990-04-12' nationality: type: string description: Código de país ISO 3166-1 alpha-2. example: ES country: type: string description: Código ISO 3166-1 alpha-2 do país do documento. example: ES document_verified: type: boolean example: true liveness: type: boolean example: true expires_at: type: string format: date-time description: >- O momento máximo em que a sessão termina. O tempo limite por inatividade pode encerrá-la antes. example: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: type: string description: >- Para onde sua aplicação envia a pessoa após o logout. String vazia quando não definido. example: https://app.example.com/ organizations: type: array description: >- Todas as organizações de clientes às quais a pessoa pertence, quando as organizações estão ativadas. Vazio caso contrário. items: $ref: '#/components/schemas/SessionOrganization' AuthenticationMethods: type: array description: >- Como a sessão fez login, em um único valor: por exemplo `password`, `code` (código por e-mail), `magic` (link mágico), `passkey`, `phone`, `sso`, `wallet` (Didit ID Wallet) ou o nome de um método de login social. Vazio para um token de agente. items: type: string example: - password WalletVerification: type: object description: >- O que a Didit ID Wallet compartilhou no login. `null` quando a pessoa fez login de outra forma. nullable: true required: - issuer - subject properties: issuer: type: string description: O emissor da carteira. example: https://apx.didit.me/auth/idv subject: type: string description: O ID da pessoa na carteira. example: 8b7f5c1e-2d3a-4b5c-9e8f-7a6b5c4d3e2f shared_session: type: object description: >- Uma verificação que a pessoa escolheu compartilhar e que você resgata com sua própria chave de API. properties: share_token: type: string session_id: type: string from_application_id: type: string claims: type: object description: >- Os fatos verificados que a pessoa concordou em compartilhar, limitados ao que a sua aplicação solicitou. additionalProperties: oneOf: - type: boolean - type: string example: over_18: true given_name: Alex SessionOrganization: type: object required: - organization_id - organization__name - role - custom_role properties: organization_id: type: string format: uuid example: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: type: string description: O nome da organização. example: Northwind role: type: string enum: - admin - member - billing example: admin custom_role: type: object nullable: true description: A função personalizada atribuída ao membro, ou `null`. required: - key - permissions properties: key: type: string example: approver permissions: type: array items: type: string example: - payouts.approve Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: Um erro OAuth (RFC 6749, seção 5.2) ou um erro de serviço. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- O token de acesso está ausente, malformado ou expirado. Ou foi assinado por outro emissor ou outra chave, é um ID token ou um token de agente, ou foi substituído por uma renovação (refresh). Também pode ser que a sessão dele tenha sido revogada, expirado por inatividade, ultrapassado seu tempo de vida ou deixado de atender à sua política de MFA, ou que a pessoa tenha sido bloqueada ou o e-mail dela não esteja mais verificado. Peça à pessoa que faça login novamente. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Token de acesso rejeitado value: detail: invalid_token OriginNotAllowed: description: >- A requisição trouxe um `Origin` que não é o da própria aplicação nem está entre suas origens permitidas. Requisições de servidor não enviam `Origin`. headers: Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Origem não permitida value: detail: origin_not_allowed ApplicationNotFound: description: >- O endereço pertence a uma aplicação, mas a Autenticação não está ativa para ela. No endereço `apx.didit.me`, isso indica que o ID da aplicação é desconhecido. Um endereço que não pertence a nenhuma aplicação é recusado antes de chegar ao endpoint, e essa resposta não é JSON. headers: Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: ApplicationNotFound: summary: Aplicação desconhecida value: detail: No Configuration matches the given query. RateLimited: description: >- Muitas requisições deste endereço IP para este endpoint ou, em um `POST` ou `DELETE`, um bucket de proteção contra bots está vazio. Nada foi executado: aguarde `Retry-After` segundos e tente novamente. headers: Retry-After: description: Segundos de espera antes de tentar novamente. schema: type: integer example: 60 Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Limite do endpoint value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Limite de proteção contra bots (POST e DELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- Um serviço do qual a requisição depende está temporariamente indisponível. Tente novamente com backoff. headers: Cache-Control: description: 'Sempre `no-store`: nunca armazene esta resposta em cache.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: Tentar novamente mais tarde value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- O token de acesso da pessoa obtido em `POST /token/`: um JWT ES256 com o cabeçalho `typ: at+jwt`, válido por no máximo 5 minutos. Não é a sua chave de API da Didit. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.