openapi: "3.0.2"
info:
  title: NoPass.me API Documentation
  version: "1.0"
  description: |
    [NoPass.me](https://nopass.me) makes it easy to authenticate users without pre-verified accounts. Common use cases include: authenticating chatbot users, verifying access to email addresses, password changes or recovery...

    This service is available as a self-hosted solution (see [Github](https://github.com/Clevyio/nopass.me)) or as a free SaaS software.

    NoPass.me (both SaaS and self-hosted versions) lets you issue, then validate, unique one-time passwords for each account you are looking to authenticate.

    The account validation flow is in 2 steps and goes as follows:

    ![](https://github.com/Clevyio/nopass.me/raw/main/images/diagram.png)

    On your end, you only need to:
    - initiate an authentication flow when you need to verify a user's identity
    - verify the user's code when the user enters their authentication code

    If the code is valid (correct code, within the validity window), it means that the user is probably who they say they are. Otherwise (incorrect or expired code), you will receive an unsuccessful response from NoPass.me: you should not let the user in!

    NoPass.me handles the full security workflow for you: generating and sending the code, verifying its validity, rejecting invalid or expired codes, and cleaning up all data afterwards. It is completely safe: **no user data is ever stored in clear text!**


servers:
  - url: https://api.nopass.me/v1
security:
  - ApiKeyAuth: []

paths:
  /verify/init:
    post:
      summary: Generate and send an authentication code
      description: Generate and send an authentication code
      operationId: init
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InitRequest"
      responses:
        "201":
          description: Success Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InitResponse"
        default:
          description: Error Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /verify/validate:
    post:
      summary: Validate an authentication code
      description: Validate an authentication code. Any unsuccessful response (either the response code is not 200 or an error is generated or `response.body.success` is not true) means that the code given by the user is not valid.
      operationId: validate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateRequest"
      responses:
        "200":
          description: Success Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateResponse"
        default:
          description: Error Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

  schemas:
    InitRequest:
      type: object
      required:
        - target
      properties:
        target:
          type: string
          description: Actual target to verify. If target_type is email, should be a valid email address
          example: john.doe@company.com
          format: email
        target_type:
          type: string
          description: Type of target. Currently only email is supported
          enum: ["email"]
          example: email
          default: email
        subject:
          type: string
          description: Subject line of the notification email
          maxLength: 256
          example: Your NoPass.me Authorization Code
          default: Your NoPass.me Authorization Code
        content:
          type: string
          description: HTML content for the notification email
          pattern: '\%code\%'
          maxLength: 1000
          example: <h1>Hello 👋</h1>\n\n<p>Your authentication code is <b>%code%</b>.</p>\n\n<p>Stay safe on the internet!</p><p>The <a href="https://nopass.me">NoPass.me</a> team</p>
          default: <h1>Hello 👋</h1>\n\n<p>Your authentication code is <b>%code%</b>.</p>\n\n<p>Stay safe on the internet!</p><p>The <a href="https://nopass.me">NoPass.me</a> team</p>
        expires_in:
          type: integer
          description: In seconds, the duration of the authentication code
          example: 300
          default: 300
          minimum: 0
          maximum: 604800

    InitResponse:
      type: object
      properties:
        success:
          type: boolean

    ValidateRequest:
      type: object
      required:
        - target
        - code
      properties:
        target:
          type: string
          description: Actual target to verify. If target_type is email, should be a valid email address
          example: john.doe@company.com
          format: email
        target_type:
          type: string
          description: Type of target. Currently only email is supported
          enum: ["email"]
          example: email
          default: email
        code:
          type: integer
          example: 123456
          description: The code received by the target

    ValidateResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the code is valid or not

    Error:
      type: object
      properties:
        message:
          type: string