Hanko Session Management API

openapi: 3.2.0
info:
  version: 1.2.0
  title: Hanko Public Session Management API
  description: '## Introduction


    This is the OpenAPI specification for the [Hanko Public API](https://github.com/teamhanko/hanko/blob/main/backend/README.md#basic-usage).


    ## Authentication


    The API uses [JSON Web Tokens](https://www.rfc-editor.org/rfc/rfc7519.html) (JWTs) for authentication.

    JWTs are verified using [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517) (JWK).

    JWKs can be [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)

    through the `secrets.keys` options. The API also publishes public cryptographic keys as a

    [JWK set](https://www.rfc-editor.org/rfc/rfc7517#section-2) through the `.well-known/jwks.json` endpoint

    to enable clients to verify token signatures.

    JWTs must be provided on requests to protected endpoints using one of the following schemes:


    ### CookieAuth


    **Security Scheme Type**: `API Key`


    **Cookie parameter name**: `hanko`


    The JWT must be provided in a Cookie with the name `hanko`.


    ### BearerTokenAuth


    **Security Scheme Type**: `http`


    **HTTP Authorization Scheme**: `Bearer`


    **Bearer format**: `JWT`


    The JWT must be provided in an HTTP Authorization header with bearer type: `Authorization: Bearer <JWT>`.


    ## Cross-Origin Resource Sharing

    Cross-Origin Resource Sharing (CORS) can be currently

    [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)

    for public endpoints via the `server.public.cors` options.


    ---

    '
  contact:
    email: developers@hanko.io
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.txt
servers:
- url: https://{tenant_id}.hanko.io
  variables:
    tenant_id:
      default: ''
      description: The (UU)ID of a tenant. Replace the default value with your tenant ID.
tags:
- name: Session Management
paths:
  /sessions/validate:
    get:
      tags:
      - Session Management
      summary: Validate a session
      description: 'Validate a session using a cookie header or an authorization header.

        This is a passive check that does not update the session''s internal last activity timestamp.

        '
      security:
      - CookieAuth: []
      - BearerTokenAuth: []
      responses:
        '200':
          $ref: '#/components/responses/ValidateSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Session Management
      summary: Validate a session
      description: 'Validate a session using a session token in a request body.

        This endpoint updates the session''s internal last activity timestamp. This extends the idle timeout window

        if configured).

        '
      requestBody:
        content:
          application/json:
            schema:
              properties:
                session_token:
                  description: The session token (JWT) to validate
                  type: string
                  format: JWT
              required:
              - session_token
      responses:
        '200':
          $ref: '#/components/responses/ValidateSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
    ValidateSessionResponse:
      description: Session validation response
      content:
        application/json:
          schema:
            properties:
              is_valid:
                description: Indicates whether the session is valid or not
                type: boolean
              expiration_time:
                description: Date-time indicating the expiration of the session. Deprecated, please use `claims.expiration` instead.
                type: string
                format: date-time
                deprecated: true
              user_id:
                description: The ID of the user the session is associated with. Deprecated, please use `claims.subject` instead.
                type: string
                format: uuid4
                deprecated: true
              claims:
                $ref: '#/components/schemas/JWTClaims'
              idle_expires_at:
                description: 'Timestamp (in UTC) indicating when the session will expire due to inactivity, assuming no further activity occurs before this time.

                  Only present when idle timeout is configured. The value is capped to the JWT expiration time.

                  '
                type: string
                format: date-time
            required:
            - isValid
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    JWTClaims:
      type: object
      description: The claims extracted from a JWT.
      properties:
        subject:
          description: The unique identifier of the token's subject.
          allOf:
          - $ref: '#/components/schemas/UUID4'
        issued_at:
          description: The timestamp indicating when the token was issued.
          type: string
          format: date-time
        expiration:
          description: The timestamp indicating when the token will expire.
          type: string
          format: date-time
        audience:
          description: The intended audience of the token.
          type: array
          items:
            type: string
        issuer:
          description: The entity that issued the token.
          type: string
        email:
          description: Data about the email address associated with the token's subject, if available.
          type: object
          properties:
            address:
              description: The actual email address.
              type: string
              format: email
            is_primary:
              description: Indicates whether the email address is the primary address.
              type: boolean
            is_verified:
              description: Indicates whether the email address is verified.
              type: boolean
        session_id:
          description: The unique identifier for the session associated with this token.
          allOf:
          - $ref: '#/components/schemas/UUID4'
        amr:
          description: Authentication Method References, JSON array of strings that are identifiers for authentication methods used in the authentication.
          type: array
          items:
            type: string
            enum:
            - pwd
            - passkey
            - otp
            - ext:<provider>
            - totp
            - security_key
            description: '- `pwd` => password

              - `passkey` => passkey

              - `otp` => email passcode

              - `ext:<provider>` => thirdparty provider, where <provider> is the internal provider ID, e.g. `ext:microsoft`

              - `totp` => 2FA authenticator app

              - `security_key` => 2FA security key

              '
      required:
      - subject
      - expiration
      - session_id
    UUID4:
      type: string
      format: uuid4
      example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c
  securitySchemes:
    CookieAuth:
      type: apiKey
      in: cookie
      name: hanko
    BearerTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: More about Hanko
  url: https://github.com/teamhanko/hanko