{
  "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).\n\nThe response contains encrypted session data. The front end then uses the session data to make the required server-side calls for the component.\n\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",
        "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.\n\nFor [Onboarding components](https://docs.adyen.com/platforms/onboard-users/components), set this to **onboarding**.\n\nFor [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.\nFor [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.\n\nFor [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.\n\nFor [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.\n\nPossible values: **accountHolder**, **legalEntity**.\n\nYou 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"
}