Hanko Third Party API

openapi: 3.2.0
info:
  version: 1.2.0
  title: Hanko Public Third Party 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: Third Party
paths:
  /thirdparty/auth:
    get:
      deprecated: true
      summary: Initialize third party login
      description: 'Initialize an OAuth-backed (authorization code grant type) login with a third party provider by redirecting to

        the specified provider login URL to retrieve an authorization code.

        '
      operationId: thirdPartyAuth
      tags:
      - Third Party
      parameters:
      - in: query
        name: provider
        required: true
        schema:
          type: string
          enum:
          - google
          - github
        description: 'The name of the third party provider to log in with. Only providers enabled in the

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

          via the `thirdparty.providers` option can be used. Requesting an unsupported provider results in a

          redirect with error details in the location query.

          '
      - in: query
        name: redirect_to
        required: true
        schema:
          type: string
          format: base64url
        description: 'Base64url encoded string representing the URL the

          [`/callback`](#tag/Third-Party/operation/thirdPartyCallback) eventually redirects to after successful login

          with the third party provider. It must match one of the allowed redirect URLs set in the backend

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

          through the `third_party.allowed_redirect_urls`.

          '
      responses:
        '307':
          description: Redirect to third party provider
          headers:
            Location:
              schema:
                type: string
              description: 'Redirect to the third party provider on success. On error, redirects to the `Referer`. If `Referer` is

                not present, redirects to the `third_party.error_redirect_url` set in the backend

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

                Error details are provided in the location URL in the form of `error` and `error_description`

                query params.

                '
  /thirdparty/callback:
    get:
      summary: Third party provider callback
      description: Callback endpoint called by the third party provider after successful login.
      operationId: thirdPartyCallback
      tags:
      - Third Party
      parameters:
      - in: query
        name: code
        schema:
          type: string
        description: 'The authorization code that can be exchanged for an access token and to retrieve user provider data

          '
      - in: query
        name: state
        required: true
        schema:
          type: string
        description: The state
      - in: query
        name: error
        schema:
          type: string
        description: 'An error returned from the third party provider

          '
      - in: query
        name: error_description
        schema:
          type: string
        description: The description of the error that occurred (if any)
      responses:
        '307':
          description: Redirect to requested redirect URL or to configured site redirect URL
          headers:
            Location:
              schema:
                type: string
              description: 'Redirect to the URL requested via `redirect_to` query parameter during third party

                provider login via [`/auth`](#tag/Third-Party/operation/thirdPartyAuth) endpoint on success. On error,

                redirect to the `third_party.error_redirect_url` set in the backend

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

                Error details are provided in the location URL in the form of `error` and `error_description`

                query params.

                '
            X-Auth-Token:
              description: 'Present only on successful callback and when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header`

                for purposes of cross-domain communication between client and Hanko API.

                '
              schema:
                $ref: '#/components/schemas/X-Auth-Token'
            Set-Cookie:
              description: 'Present only on successful callback. Contains the JSON Web Token (JWT) that must be provided to protected endpoints.

                Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`.

                '
              schema:
                $ref: '#/components/schemas/CookieSession'
components:
  schemas:
    CookieSession:
      type: string
      description: Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)
      example: hanko=<JWT>; Path=/; HttpOnly
    X-Auth-Token:
      description: 'Enable via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header`

        for purposes of cross-domain communication between client and Hanko API.

        '
      type: string
      format: JWT
      externalDocs:
        url: https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config
  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