Weavr Sign-in API

openapi: 3.2.0
info:
  version: v3
  title: Weavr Multi Product Sign In API
  x-logo:
    url: https://storage.googleapis.com/weavr-cdn/weavr_logo-new.png
    backgroundColor: '#FFFFFF'
    altText: Weavr
  description: 'Weavr Multi API provides a simple and flexible way to issue cards and accounts to your customers.


    By integrating Weavr Multi API in your application you can embed banking capabilities within your app and provide a seamless experience for your customers.


    # Authentication


    Each request to the Multi API must include an `api-key` that represents your account. You can obtain an API Key by registering for a Multi account [here](https://portal.weavr.io).


    Almost all endpoints require a secondary authentication token `auth_token` that represents the user for whom the request is being executed.

    '
  contact:
    name: Weavr
    url: https://weavr.io
servers:
- description: Weavr Sandbox Environment
  url: https://sandbox.weavr.io/multi
tags:
- name: Sign-in
  description: Sign users in using passwords, biometrics, or third-party auth providers.
paths:
  /login_with_password:
    post:
      tags:
      - Sign-in
      description: 'Authenticate a user with the `email` and `password` that they provided when registering.


        Given that the user credentials are correct, this returns a `token` that can then be used to authorise

        other secured operations. In case the password is expired, a temporary `token` is returned, which can be used

        solely for updating the password.


        The token returned is valid for 5 minutes from last activity.

        '
      summary: Sign in with password
      operationId: loginWithPassword
      requestBody:
        $ref: '#/components/requestBodies/LoginWithPasswordRequest'
      responses:
        '200':
          $ref: '#/components/responses/LoginWithPasswordResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The authentication credentials are not found or are incorrect.
        '404':
          $ref: '#/components/responses/NotFoundToken'
        '409':
          $ref: '#/components/responses/LoginWithPasswordConflict'
        '410':
          $ref: '#/components/responses/TokenExpired'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - api-key: []
  /login_via_biometrics:
    post:
      tags:
      - Sign-in
      description: "Trigger a push notification and subsequent biometric authentication of a user, by providing the email that was \nused in the enrolment process of biometrics.\n\nThis endpoint can be used in conjunction with your application to authenticate a user and receive a stepped-up \ntoken in a single action, for use in-session for any endpoints or UI components that require step-up \nauthentication.\n\nGiven that the user credentials are correct, a push notification is sent to the user requesting them to complete\nbiometric authentication. On successful completion of authentication, a token will be shared that can be used \nfor endpoints or UI components that require a stepped-up token.\n"
      summary: Sign in via biometrics
      operationId: loginViaBiometrics
      requestBody:
        $ref: '#/components/requestBodies/LoginViaBiometricsRequest'
      responses:
        '200':
          $ref: '#/components/responses/LoginViaBiometricsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The authentication credentials are not found or are incorrect.
        '409':
          $ref: '#/components/responses/LoginViaBiometricsConflict'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - api-key: []
  /logout:
    post:
      tags:
      - Sign-in
      deprecated: true
      description: Logs out the user and terminates the session identified by the `auth_token` in the Authorization Header.
      summary: Logout
      operationId: logout
      responses:
        '200':
          $ref: '#/components/responses/LogoutResponse'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
components:
  responses:
    InternalServerError:
      description: Internal Server Error - There is a problem with the server. Please try again later.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    LogoutResponse:
      description: Success
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              url:
                type: string
                description: The logout url for third party auth providers.
    TooManyRequests:
      description: Too many requests.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
        x-ratelimit-limit:
          $ref: '#/components/headers/x-ratelimit-limit'
        x-ratelimit-reset:
          $ref: '#/components/headers/x-ratelimit-reset'
    Unauthorized:
      description: Unauthorized - Your credentials or access token are invalid.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    LoginWithPasswordConflict:
      description: The user's password has expired. Use the returned temporary token to update their password via the  '_/passwords/update_' endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              token:
                type: string
                description: Temporary authorisation token required to initiate the _passwordUpdate_ operation.
    NotFoundToken:
      description: Not found - The requested token couldn't be found.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenError'
    LoginViaBiometricsResponse:
      description: Success
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              challengeId:
                type: string
                description: The unique identifier of a Biometric challenge.
    TokenExpired:
      description: Gone - The requested token is expired.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenError'
    LoginViaBiometricsConflict:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: string
                enum:
                - CHANNEL_NOT_REGISTERED
                - CHANNEL_NOT_SUPPORTED
    LoginWithPasswordResponse:
      description: Success
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              token:
                type: string
                description: An authorisation token (valid for 5 minutes from last activity) identifying the user to be used in the `auth_token` authorization header for secured operations.
              tokenType:
                $ref: '#/components/schemas/TokenType'
              identity:
                description: The identity to which the logged-in user belongs to.
                $ref: '#/components/schemas/IdentityId'
              credentials:
                description: The unique identifier for the logged-in user.
                $ref: '#/components/schemas/CredentialId'
    NoContent:
      description: Success - No Content.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    BadRequestError:
      description: Bad Request Error - Your request is invalid.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                maxLength: 255
                type: string
                description: When present helps to identify and fix the problem.
              syntaxErrors:
                $ref: '#/components/schemas/SyntaxError'
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: Service Unavailable - The requested service is temporarily unavailable. Please try again later.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    Locked:
      description: Locked - Account is temporarily locked due to failed consecutive login attempts. Try again in 30 minutes.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
  schemas:
    CredentialId:
      required:
      - type
      - id
      type: object
      properties:
        type:
          maxLength: 50
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
          enum:
          - ROOT
          - USER
          - API_CLIENT
          description: The type of user.
        id:
          type: string
          pattern: ^[0-9]+$
          description: The identifier of the user.
    TokenError:
      description: The used token is expired or not found
      type: object
      properties:
        errorCode:
          type: string
          enum:
          - TOKEN_EXPIRED
          - TOKEN_NOT_FOUND
    SyntaxError:
      type: object
      description: Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.
      properties:
        invalidFields:
          type: array
          items:
            type: object
            properties:
              params:
                type: array
                items:
                  type: string
              fieldName:
                type: string
              error:
                type: string
                enum:
                - REQUIRED
                - HAS_TEXT
                - REQUIRES
                - SIZE
                - RANGE
                - IN
                - NOT_IN
                - REGEX
                - EXACTLY
                - AT_LEAST
                - AT_MOST
                - ALL_OR_NONE
    TokenType:
      type: string
      description: "The auth token received can only be used to access the following endpoints:\n  - `/identities`\n  - `/access_token`\n"
      enum:
      - NO_TYPE
      - AUTH
      - ACCESS
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    IdentityId:
      required:
      - type
      - id
      type: object
      properties:
        type:
          enum:
          - CONSUMER
          - CORPORATE
          type: string
          description: Indicates the identity type.
        id:
          type: string
          pattern: ^[0-9]+$
          description: The identifier for the identity.
    Email:
      type: string
      description: E-mail Address of the user
      format: email
    SensitivePassword:
      type: object
      description: "The user's password or passcode used to log in a user.\nPasswords must be:\n  - minimum 8 characters for end-users (Consumers and Corporates); 12 characters for others\n  - maximum 30 characters\n  - include a lowercase character\n  - include an uppercase character\n  - include a digit and a special character\n  - different from any of the 5 last such passwords used.\n\nFor non-PCI compliant integrations, the password submitted must be **tokenised**.\n"
      required:
      - value
      properties:
        value:
          maxLength: 100
          type: string
          format: password
  headers:
    request-ref:
      description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
      required: true
      schema:
        type: string
    x-ratelimit-reset:
      description: The number of seconds until the window is reset.
      required: true
      schema:
        minimum: 0
        type: integer
        format: int32
    x-ratelimit-limit:
      description: 'Example: `20, 10;w=60, 20;w=3600, 200;w=86400`

        The first number (20) is the limit that has been exceeded.

        The remaining numbers are the limits that are in force, with ''w'' meaning ''window in seconds''. In this example `20;w=3600` was exceeded. 20 calls in 3600secs (1hr)

        '
      required: true
      schema:
        type: string
  requestBodies:
    LoginViaBiometricsRequest:
      required: true
      content:
        application/json:
          schema:
            required:
            - email
            type: object
            properties:
              email:
                $ref: '#/components/schemas/Email'
              identity:
                $ref: '#/components/schemas/IdentityId'
    LoginWithPasswordRequest:
      required: true
      content:
        application/json:
          schema:
            required:
            - email
            - password
            type: object
            properties:
              email:
                $ref: '#/components/schemas/Email'
              password:
                $ref: '#/components/schemas/SensitivePassword'
  securitySchemes:
    api-key:
      type: apiKey
      description: An API key defined in your User API Client  (or Delegate API Client - this feature is available only to customers enabled with delegation functionality).  API Clients are as managed in the Embedder Portal
      name: api-key
      in: header
    auth_token:
      type: http
      description: The authentication token representing the user. This will be included in the login response object.
      scheme: bearer
      bearerFormat: JWT
    webhooks_key:
      type: apiKey
      description: The Webhooks key can be found in the API Credentials tab in your Portal Page.
      name: webhooks-key
      in: header
x-tagGroups:
- name: Customer Registration
  tags:
  - Corporates
  - Consumers
- name: Users & User Authentication
  tags:
  - Setup
  - Sign-in
  - Step-up Challenges
  - Confirmation Challenges
  - Authentication Factors
- name: Access
  tags:
  - Access Tokens
- name: Customer Settings
  tags:
  - Customer Data & Due Diligence
  - Authorised Signatories
  - Trusted Payees
- name: Instruments
  tags:
  - Managed Accounts
  - Managed Cards
- name: Funds Management
  tags:
  - Transfers
  - Transaction Activity
- name: External Payments
  tags:
  - Incoming Wire Transfers
  - Outgoing Wire Transfers
  - Correspondent Bank Transfers
- name: Card Payments
  tags:
  - Card Payments
  - Spend Controls
- name: In-Platform Payments
  tags:
  - Sends
  - Fees
- name: Bulk Operations
  tags:
  - Operations
  - Manage