openapi: 3.1.0
servers:
- url: https://test.adyen.com/authe/api/v1
  description: Test Environment
- url: https://authe-live.adyen.com/authe/api/v1
  description: Live Environment
info:
  title: Session authentication API
  description: "The Session authentication API enables you to create and manage the\
    \ JSON Web Tokens (JWT) required for integrating [components](https://docs.adyen.com/platforms/components-overview).\n\
    ## Authentication\nWe recommend that you use an API key to connect to the Session\
    \ authentication API. Generate an API key in your Customer Area if you have a\
    \ [platform setup](https://docs.adyen.com/platforms/manage-access/api-credentials-web-service/#generate-api-key)\
    \ or [marketplace setup](https://docs.adyen.com/marketplaces/manage-access/api-credentials-web-service/#generate-api-key).\
    \ If you have an Adyen Issuing integration, [generate an API key](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service/#generate-api-key)\
    \ in your Balance Platform Customer Area.\n\nTo connect to the Session authentication\
    \ API, add an `X-API-Key` header with the API key as the value, for example:\n\
    \n ```\ncurl\n-H 'Content-Type: application/json' \\\n-H 'X-API-Key: YOUR_API_KEY'\
    \ \\\n...\n```\n\n## Roles and permissions\nTo create a token, you must meet specific\
    \ requirements. These requirements vary depending on the type of component. For\
    \ more information, see the documentation for [Onboarding](https://docs.adyen.com/platforms/onboard-users/components)\
    \ and [Platform Experience](https://docs.adyen.com/platforms/build-user-dashboards)\
    \ components.\n\n## Going live\nTo access the live endpoint, generate an API key\
    \ in your live Customer Area if you have a [platform](https://docs.adyen.com/platforms/)\
    \ or [marketplace setup](https://docs.adyen.com/marketplaces/). If you have an\
    \ Adyen Issuing integration, [generate an API key](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service/#generate-api-key)\
    \ in your Balance Platform Customer Area. You can then use the API key to send\
    \ requests to `https://authe-live.adyen.com/authe/api/v1`.\n\n"
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
  version: '1'
  x-timestamp: '2025-02-11T15:30:46Z'
tags:
- name: Session authentication
paths:
  /sessions:
    post:
      tags:
      - Session authentication
      summary: Create a session token
      description: 'Creates a session token that is required to integrate [components](https://docs.adyen.com/platforms/components-overview).


        The response contains encrypted session data. The front end then uses the
        session data to make the required server-side calls for the component.


        To create a token, you must meet specific requirements. These requirements
        vary depending on the type of component. For more information, see the documentation
        for [Onboarding](https://docs.adyen.com/platforms/onboard-users/components)
        and [Platform Experience](https://docs.adyen.com/platforms/build-user-dashboards)
        components.


        '
      operationId: post-sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationSessionRequest'
            examples:
              create-session-platform:
                summary: Create a session token for platform components
                description: The request describes a subset of resources and permissions
                  expected from the requested session
                value:
                  allowOrigin: https://www.your-website.com
                  product: platform
                  policy:
                    resources:
                    - type: accountHolder
                      accountHolderId: AH00000000000000000000001
                    roles:
                    - 'Transactions Overview Component: View'
                    - 'Payouts Overview Component: View'
              create-session-onboarding:
                summary: Create a session token for onboarding components
                description: The request describes a subset of resources and permissions
                  expected from the requested session
                value:
                  allowOrigin: https://www.your-website.com
                  product: onboarding
                  policy:
                    resources:
                    - type: legalEntity
                      legalEntityId: LE00000000000000000000001
                    roles:
                    - createTransferInstrumentComponent
                    - manageTransferInstrumentComponent
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationSessionResponse'
              examples:
                create-session-platform:
                  summary: Session token created
                  description: Response to be proxied to embedded components
                  value:
                    id: 11a1e60a-18b0-4dda-9258-e0ae29e1e2a3
                    token: eyJraWQiOiJwbGF0Zm9ybWNvbGRlciI...
                create-session-onboarding:
                  summary: Session token created
                  description: Response to be proxied to embedded components
                  value:
                    id: 11a1e60a-18b0-4dda-9258-e0ae29e1e2a3
                    token: eyJraWQiOiJwbGF0Zm9ybWNvbGRlciI...
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                create-session-400:
                  summary: Bad request
                  description: Response returned when request parsing has failed or
                    some request fields were invalid.
                  value:
                    type: https://docs.adyen.com/errors/bad-request
                    errorCode: '00_400'
                    title: Bad request
                    detail: Unable to map request body
                    requestId: c49d45e20aec9a0f20c908343da5ebc3
                    status: 400
                    invalidFields:
                    - name: product
                      message: Field key/value incorrect
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                create-session-401:
                  summary: Unauthorized
                  description: Authentication failed.
                  value:
                    type: https://docs.adyen.com/errors/unauthorized
                    title: Unauthorized
                    status: 401
                    errorCode: '00_401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                create-session-403:
                  summary: Forbidden
                  description: Most commonly happens when user does not have sufficient
                    roles or doesn't own requested resource.
                  value:
                    type: https://docs.adyen.com/errors/forbidden
                    errorCode: '00_403'
                    title: Forbidden
                    detail: User doesn't have access to all token policy resources
                    requestId: d42c493b5176df89e51516c6060cc34c
                    status: 403
      x-methodName: createAuthenticationSession
      x-sortIndex: 0
components:
  schemas:
    AccountHolderResource:
      required:
      - accountHolderId
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          accountHolderId:
            type: string
            description: The unique identifier of the resource connected to the component.
              For [Platform Experience components](https://docs.adyen.com/platforms/build-user-dashboards),
              this is the account holder linked to the balance account shown in the
              component.
    AuthenticationSessionRequest:
      required:
      - allowOrigin
      - policy
      - product
      type: object
      properties:
        allowOrigin:
          type: string
          description: The URL where the component will appear. In your live environment,
            you must protect the URL with an SSL certificate and ensure that it starts
            with `https://`.
        policy:
          description: An object that contains a description of the allowed resources
            and roles for the requested session.
          $ref: '#/components/schemas/Policy'
        product:
          description: 'The type of component.


            For [Onboarding components](https://docs.adyen.com/platforms/onboard-users/components),
            set this to **onboarding**.


            For [Platform Experience components](https://docs.adyen.com/platforms/build-user-dashboards),
            set this to **platform**.'
          $ref: '#/components/schemas/ProductType'
    BalanceAccountResource:
      required:
      - balanceAccountId
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          balanceAccountId:
            type: string
    LegalEntityResource:
      required:
      - legalEntityId
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          legalEntityId:
            type: string
            description: 'The unique identifier of the resource connected to the component.

              For [Onboarding components](https://docs.adyen.com/platforms/onboard-users/components),
              this is the legal entity that has a contractual relationship with your
              platform and owns the [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments).
              For sole proprietorships, this is the legal entity of the individual
              owner.'
    MerchantAccountResource:
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          merchantAccountCode:
            type: string
    PaymentInstrumentResource:
      required:
      - paymentInstrumentId
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          paymentInstrumentId:
            type: string
    Policy:
      type: object
      properties:
        resources:
          uniqueItems: true
          type: array
          description: 'An object containing the type and the unique identifier of
            the user of the component.


            For [Onboarding components](https://docs.adyen.com/platforms/onboard-users/components),
            this is the ID of the legal entity that has a contractual relationship
            with your platform. For sole proprietorships, use the ID of the legal
            entity of the individual owner.


            For [Platform Experience components](https://docs.adyen.com/platforms/build-user-dashboards),
            this is the ID of the account holder that is associated with the balance
            account shown in the component.'
          items:
            $ref: '#/components/schemas/Resource'
        roles:
          uniqueItems: true
          type: array
          description: The name of the role required to use the component.
          items:
            type: string
    ProductType:
      type: string
      enum:
      - onboarding
      - platform
    Resource:
      type: object
      properties:
        type:
          description: 'The resource type.


            Possible values: **accountHolder**, **legalEntity**.


            You must also include the corresponding unique identifier of the resource.
            For example, the account holder ID.'
          $ref: '#/components/schemas/ResourceType'
      discriminator:
        propertyName: type
        mapping:
          legalEntity: '#/components/schemas/LegalEntityResource'
          balanceAccount: '#/components/schemas/BalanceAccountResource'
          accountHolder: '#/components/schemas/AccountHolderResource'
          merchantAccount: '#/components/schemas/MerchantAccountResource'
          paymentInstrument: '#/components/schemas/PaymentInstrumentResource'
    ResourceType:
      type: string
      enum:
      - legalEntity
      - balanceAccount
      - accountHolder
      - merchantAccount
      - paymentInstrument
    AuthenticationSessionResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the session.
        token:
          type: string
          description: The session token created.
    DefaultErrorResponseEntity:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of
            the problem.
        errorCode:
          type: string
          description: Unique business error code.
        instance:
          type: string
          description: A URI that identifies the specific occurrence of the problem
            if applicable.
        invalidFields:
          type: array
          description: Array of fields with validation errors when applicable.
          items:
            $ref: '#/components/schemas/InvalidField'
        requestId:
          type: string
          description: The unique reference for the request.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        type:
          type: string
          description: A URI that identifies the validation error type. It points
            to human-readable documentation for the problem type.
      description: Standardized error response following RFC-7807 format
      externalDocs:
        url: https://www.rfc-editor.org/rfc/rfc7807
    InvalidField:
      required:
      - message
      - name
      - value
      type: object
      properties:
        name:
          type: string
          description: The field that has an invalid value.
        value:
          type: string
          description: The invalid value.
        message:
          type: string
          description: Description of the validation error.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    BasicAuth:
      type: http
      scheme: basic
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base