swagger.yaml

swagger: "2.0" # https://stackoverflow.com/a/59749691/14797322

info:
  title: "magiclinks.dev"
  description: "The v2 API specification for the magiclinksdev project.
  \n\n
  The default JWK Set relative URL path is `/api/v2/jwks.json`.
  \n\n
  The documentation site is at https://docs.magiclinks.dev
  \n
  This is an Apache License 2.0 project: https://github.com/MicahParks/magiclinksdev
  \n
  The optional SaaS platform's landing page is: https://magiclinks.dev
  "
  version: "2.0.0"

host: "magiclinks.dev"
basePath: "/api/v2"

schemes:
  - "https"

consumes:
  - "application/json"
produces:
  - "application/json"

paths:
  /ready:
    get:
      summary: "Check if the service is ready to accept requests."
      operationId: "ready"
      responses:
        200:
          description: "The service is ready to accept requests."
        default:
          description: "The service is not ready to accept requests."

  /admin/service-account/create:
    post:
      tags:
        - "admin"
      summary: "Create a new service account."
      operationId: "serviceAccountCreate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/ServiceAccountCreateRequest"
      responses:
        201:
          description: "The service account has been created."
          schema:
            $ref: "#/definitions/ServiceAccountCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /jwt/create:
    post:
      summary: "Create a JWT, typically after OTP verification or a JWT refresh."
      operationId: "jwtCreate"
      parameters:
        - name: "body"
          in: "body"
          required: true
          schema:
            $ref: "#/definitions/JWTCreateRequest"
      responses:
        201:
          description: "The JWT was created."
          schema:
            $ref: "#/definitions/JWTCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /jwt/validate:
    post:
      summary: "Verify and validate a JWT."
      operationId: "jwtValidate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/JWTValidateRequest"
      responses:
        200:
          description: "The JWT is verified and validated."
          schema:
            $ref: "#/definitions/JWTValidateResponse"
        422:
          description: "The JWT failed verification and validation."
          schema:
            $ref: "#/definitions/Error"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /magic-link/create:
    post:
      summary: "Create a magic link."
      operationId: "magicLinkCreate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/MagicLinkCreateRequest"
      responses:
        201:
          description: "The magic link was created."
          schema:
            $ref: "#/definitions/MagicLinkCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /magic-link-email/create:
    post:
      summary: "Create a magic link and send it via email."
      operationId: "magicLinkEmailCreate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/MagicLinkEmailCreateRequest"
      responses:
        201:
          description: "The magic link has been created and the email request has been accepted by the provider."
          schema:
            $ref: "#/definitions/MagicLinkEmailCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /otp/create:
    post:
      summary: "Create a One-Time Password (OTP)."
      operationId: "otpCreate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/OTPCreateRequest"
      responses:
        201:
          description: "The OTP was created."
          schema:
            $ref: "#/definitions/OTPCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /otp/validate:
    post:
      summary: "Verify and validate a One-Time Password (OTP) given its ID."
      operationId: "otpValidate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/OTPValidateRequest"
      responses:
        200:
          description: "The OTP is verified and valid for the given ID."
          schema:
            $ref: "#/definitions/OTPValidateResponse"
        400:
          description: "The OTP failed verification or validation for the given ID."
          schema:
            $ref: "#/definitions/Error"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

  /otp-email/create:
    post:
      summary: "Create a One-Time Password (OTP) and sent it via email."
      operationId: "otpEmailCreate"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/OTPEmailCreateRequest"
      responses:
        201:
          description: "The OTP has been created and the email request has been accepted by the provider."
          schema:
            $ref: "#/definitions/OTPEmailCreateResponse"
        default:
          description: "An unexpected error occurred."
          schema:
            $ref: "#/definitions/Error"

definitions:
  Error:
    type: "object"
    properties:
      code:
        type: "integer"
        description: "A copy of the HTTP response status code."
        format: "int32"
      message:
        type: "string"
        description: "A human-readable error message."
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  RequestMetadata:
    type: "object"
    properties:
      uuid:
        type: "string"
        description: "A UUID that uniquely identifies the request."
        format: "uuid"

  ServiceAccount:
    type: "object"
    properties:
      uuid:
        type: "string"
        format: "uuid"
      apiKey:
        type: "string"
      aud:
        type: "string"
      admin:
        type: "boolean"

  JWTCreateParams:
    description: "Parameters used to create a JWT."
    type: "object"
    properties:
      alg:
        description: "The algorithm to use when signing the JWT. It defaults depends on the server's configuration. The
        default server configuration is \"EdDSA\". The default server options are \"EdDSA\" and \"RS256\"."
        type: "string"
      claims:
        description: 'Any valid JSON object. Do not provide any JSON attributes mentioned in RFC 7519 section 4.1 as
        this will cause an error. These are JWT "Registered Claim Names".'
        type: "object"
        externalDocs:
          description: "RFC 7519 section 4.1"
          url: "https://tools.ietf.org/html/rfc7519#section-4.1"
      lifespanSeconds:
        description: "The lifespan of the JWT in seconds. The JWT's lifespan starts after creation. For magic links,
        after the magic link has been visited. It defaults to 5 minutes. The minimum value is 5 seconds and the maximum
        value is 7905600000 seconds, which is a bit over 250 years."
        default: 300
        type: "integer"

  JWTCreateRequest:
    description: "The request body for the /jwt/create endpoint."
    type: "object"
    properties:
      jwtCreateParams:
        $ref: "#/definitions/JWTCreateParams"
    required:
      - "jwtCreateParams"

  JWTCreateResults:
    description: "The results for creating a JWT."
    type: "object"
    properties:
      jwt:
        description: "The signed JWT."
        type: "string"

  JWTCreateResponse:
    description: "The response body for the /jwt/create endpoint."
    type: "object"
    properties:
      jwtCreateResults:
        $ref: "#/definitions/JWTCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  JWTValidateParams:
    description: "Parameters used to validate a JWT."
    type: "object"
    properties:
      jwt:
        description: "The JWT to validate."
        type: "string"

  JWTValidateRequest:
    description: "The request body for the /jwt/validate endpoint."
    type: "object"
    properties:
      jwtValidateParams:
        $ref: "#/definitions/JWTValidateParams"
    required:
      - "jwtValidateParams"

  JWTValidateResults:
    description: "The results for validateing a JWT."
    type: "object"
    properties:
      claims:
        description: 'Any valid JSON object. Do not provide any JSON attributes mentioned in RFC 7519 section 4.1 as
        this will cause an error. These are JWT "Registered Claim Names".'
        type: "object"
        externalDocs:
          description: "RFC 7519 section 4.1"
          url: "https://tools.ietf.org/html/rfc7519#section-4.1"

  JWTValidateResponse:
    description: "The response body for the /jwt/validate endpoint."
    type: "object"
    properties:
      jwtValidateResults:
        $ref: "#/definitions/JWTValidateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  MagicLinkCreateParams:
    description: "Parameters to create a magic link."
    type: "object"
    properties:
      jwtCreateParams:
        $ref: "#/definitions/JWTCreateParams"
      lifespanSeconds:
        description: "The lifespan of the magic link in seconds. The magic link's lifespan starts after it has been
        created. It defaults to 1 hour. The minimum value is 5 seconds and the maximum value is 7905600000 seconds,
        which is a bit over 250 years."
        type: "integer"
        default: 3600
      redirectQueryKey:
        description: 'The URL query key in the redirectURL to contain the signed JWT when the magic link is used. By
        default, "jwt" is used.'
        type: "string"
      redirectURL:
        description: "The URL to redirect to with the signed JWT when the magic link is used."
        type: "string"
    required:
      - "redirectURL"

  MagicLinkCreateRequest:
    type: "object"
    properties:
      magicLinkCreateParams:
        $ref: "#/definitions/MagicLinkCreateParams"
    required:
      - "magicLinkCreateParams"

  MagicLinkCreateResults:
    type: "object"
    properties:
      magicLink:
        description: "The URL that will act as a magic link. When this URL is visited, a new JWT will be created. A
        redirect wil be performed with this new JWT in the redirect URL's query parameter."
        type: "string"
      secret:
        description: "The secret embedded in the magic link."
        type: "string"

  MagicLinkCreateResponse:
    type: "object"
    properties:
      magicLinkCreateResults:
        $ref: "#/definitions/MagicLinkCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  MagicLinkEmailCreateParams:
    description: "Parameters to create a magic link email."
    type: "object"
    properties:
      buttonText:
        description: 'The text to display on the button in the email. It defaults to "Magic link".'
        type: "string"
        default: "Magic link"
        example: "Login"
      greeting:
        description: 'The smaller text above the title.'
        type: "string"
        example: "Hello Jane Doe,"
      logoClickURL:
        description: "The URL to redirect to when the logo is clicked."
        type: "string"
        example: "https://example.com"
      logoImageURL:
        description: "The URL to the logo image to display in the email."
        type: "string"
        example: "https://example.com/logo.png"
      serviceName:
        description: "The name of your service. This is used in invisible email metadata."
        type: "string"
        example: "example.com"
      subject:
        description: 'The subject of the email. It must be between 5 and 100 characters inclusive. Make sure to include
        the name of your application.'
        type: "string"
        example: "Login to example.com"
      subTitle:
        description: "The smaller text, right above the magic link button."
        type: "string"
        example: "Login using the button below."
      title:
        description: 'The larger text, right above the subtitle. It must be between 5 and 256 characters inclusive.
        Make sure to include the name of your application.'
        type: "string"
        example: "Login to example.com with a magic link"
      toEmail:
        description: "The email address to send the magic link to."
        type: "string"
        format: "email"
        example: "jane.doe@example.com"
      toName:
        description: "The name of the recipient."
        type: "string"
        example: "Jane Doe"
    required:
      - "subject"
      - "title"
      - "toEmail"
      - "serviceName"

  MagicLinkEmailCreateRequest:
    type: "object"
    properties:
      magicLinkCreateParams:
        $ref: "#/definitions/MagicLinkCreateParams"
      magicLinkEmailCreateParams:
        $ref: "#/definitions/MagicLinkEmailCreateParams"
    required:
      - "magicLinkCreateParams"
      - "magicLinkEmailCreateParams"

  MagicLinkEmailCreateResults:
    description: "The results for creating a magic link email."
    type: "object"
    properties:
      magicLinkCreateResults:
        $ref: "#/definitions/MagicLinkCreateResults"

  MagicLinkEmailCreateResponse:
    type: "object"
    properties:
      magicLinkEmailCreateResults:
        $ref: "#/definitions/MagicLinkEmailCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  OTPCreateParams:
    description: "Parameters to create a One-Time Password (OTP)."
    type: "object"
    properties:
      charSetAlphaLower:
        description: "Include a chance to use lowercase letters in the OTP."
        type: "boolean"
      charSetAlphaUpper:
        description: "Include a chance to use uppercase letters in the OTP."
        type: "boolean"
      charSetNumeric:
        description: "Include a chance to use numbers in the OTP."
        type: "boolean"
      length:
        description: "The length of the OTP. It defaults to 6. The minimum value is 1 and the maximum value is 12."
        default: 6
        type: "integer"
      lifespanSeconds:
        description: "The lifespan of the OTP in seconds. The OTP's lifespan starts after it has been created. It
        defaults to 1 hour. The minimum value is 5 seconds and the maximum value is 7905600000 seconds, which is a bit
        over 250 years."
        default: 3600
        type: "integer"

  OTPCreateRequest:
    type: "object"
    properties:
      otpCreateParams:
        $ref: "#/definitions/OTPCreateParams"
    required:
      - "otpCreateParams"

  OTPCreateResults:
    description: "The results for creating a One-Time Password (OTP)."
    type: "object"
    properties:
      id:
        description: "The ID of the OTP."
        type: "string"
      otp:
        description: "The One-Time Password."
        type: "string"

  OTPCreateResponse:
    type: "object"
    properties:
      otpCreateResults:
        $ref: "#/definitions/OTPCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  OTPEmailCreateParams:
    description: "Parameters to create a One-Time Password (OTP) email."
    type: "object"
    properties:
      greeting:
        description: 'The smaller text above the title.'
        type: "string"
        example: "Hello Jane Doe,"
      logoClickURL:
        description: "The URL to redirect to when the logo is clicked."
        type: "string"
        example: "https://example.com"
      logoImageURL:
        description: "The URL to the logo image to display in the email."
        type: "string"
        example: "https://example.com/logo.png"
      serviceName:
        description: "The name of your service. This is used in invisible email metadata."
        type: "string"
        example: "example.com"
      subject:
        description: 'The subject of the email. It must be between 5 and 100 characters inclusive. Make sure to include
        the name of your application.'
        type: "string"
        example: "Login to example.com"
      subTitle:
        description: "The smaller text, right above the magic link button."
        type: "string"
        example: "Login using the button below."
      title:
        description: 'The larger text, right above the subtitle. It must be between 5 and 256 characters inclusive.
        Make sure to include the name of your application.'
        type: "string"
        example: "Login to example.com with a magic link"
      toEmail:
        description: "The email address to send the magic link to."
        type: "string"
        format: "email"
        example: "jane.doe@example.com"
      toName:
        description: "The name of the recipient."
        type: "string"
        example: "Jane Doe"
    required:
      - "subject"
      - "title"
      - "toEmail"
      - "serviceName"

  OTPEmailCreateRequest:
    type: "object"
    properties:
      otpCreateParams:
        $ref: "#/definitions/OTPCreateParams"
      otpEmailCreateParams:
        $ref: "#/definitions/OTPEmailCreateParams"
    required:
      - "otpCreateParams"
      - "otpEmailCreateParams"

  OTPEmailCreateResults:
    description: "The results for creating a One-Time Password (OTP) email."
    type: "object"
    properties:
      otpCreateResults:
        $ref: "#/definitions/OTPCreateResults"

  OTPEmailCreateResponse:
    type: "object"
    properties:
      otpEmailCreateResults:
        $ref: "#/definitions/OTPEmailCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

  OTPValidateParams:
    description: "Parameters to validate a One-Time Password (OTP)."
    type: "object"
    properties:
      id:
        description: "The ID of the OTP to validate."
        type: "string"
      otp:
        description: "The user provided One-Time Password to validate."
        type: "string"

  OTPValidateRequest:
    type: "object"
    properties:
      otpValidateParams:
        $ref: "#/definitions/OTPValidateParams"

  OTPValidateResults:
    type: "object"

  OTPValidateResponse:
    type: "object"
    properties:
      otpValidateResults:
        $ref: "#/definitions/OTPValidateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"
    required:
      - "otpValidateResults"
      - "requestMetadata"

  ServiceAccountCreateParams:
    description: "Parameters to create a service account."
    type: "object"

  ServiceAccountCreateRequest:
    description: "The request body for the /admin/service-account/create endpoint."
    type: "object"
    properties:
      serviceAccountCreateParams:
        $ref: "#/definitions/ServiceAccountCreateParams"

  ServiceAccountCreateResults:
    description: "The results for creating a service account."
    type: "object"
    properties:
      serviceAccount:
        $ref: "#/definitions/ServiceAccount"

  ServiceAccountCreateResponse:
    description: "The response body for the /admin/service-account/create endpoint."
    type: "object"
    properties:
      serviceAccountCreateResults:
        $ref: "#/definitions/ServiceAccountCreateResults"
      requestMetadata:
        $ref: "#/definitions/RequestMetadata"

securityDefinitions:
  apiKey:
    type: "apiKey"
    in: "header"
    name: "X-API-KEY"
security:
  - apiKey: [ ]

tags:
  - name: "admin"
    description: "Endpoints for service accounts authorized with an admin API key."