better-auth/docs/openapi.yml

openapi: 3.1.1
info:
  title: Better Auth API
  description: |
    The Better Auth API Endpoints gets documented here.

    ## Resources

    * https://github.com/better-auth/better-auth
    * https://better-auth.com
  version: 1.0.0
  contact:
    url: https://better-auth.com
servers:
  - url: '{protocol}://{baseURL}/{path}'
    description: Responds with your request data
    variables:
      baseURL:
        default: 'localhost:3000'
      protocol:
        enum:
          - https
        default: https
      path:
        default: ''
security:
  - bearerAuth: []
  - apiKeyCookie: []
tags:
  - name: Sessions
    description: Everything about sessions
  - name: Account
    description: Everything about account
  - name: Callback
    description: Everything about callback
  - name: Email Verification
    description: Everything about email verification
  - name: Forget Password
    description: Everything about forget password
  - name: Sign in
    description: Everything about sign in
  - name: Sign out
    description: Everything about sign out
  - name: Sign up
    description: Everything about sign up
  - name: Update user
    description: Everything about update user
paths:
  '/get-session':
    get:
      tags:
        - Sessions
      summary: Get current session
      descriptions: It's used to get the currently logged in session.
      operationId: getSession
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Session'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/list-sessions':
    get:
      tags:
        - Sessions
      summary: List all sessions
      descriptions: It's used to list all the sessions.
      operationId: listSessions
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  '$ref': '#/components/schemas/Session'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/revoke-session':
    post:
      tags:
        - Sessions
      summary: Revoke a session
      descriptions: It's used to revoke a session.
      operationId: revokeSession
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        description: Session ID
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/revoke-sessions':
    post:
      tags:
        - Sessions
      summary: Revoke all sessions
      descriptions: It's used to revoke all sessions.
      operationId: revokeSessions
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/revoke-other-sessions':
    post:
      tags:
        - Sessions
      summary: Revoke other sessions
      descriptions: It's used to revoke all other sessions, other than the current one.
      operationId: revokeOtherSessions
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/list-accounts':
    get:
      tags:
        - Account
      summary: List all accounts
      descriptions: It's used to list all the accounts linked to the current user.
      operationId: listAccounts
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  '$ref': '#/components/schemas/Account'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
  '/link-social':
    post:
      tags:
        - Account
      summary: Link social account
      descriptions: It's used to link social account to the current user.
      operationId: linkSocial
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        currentURL:
          name: currentURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  examples:
                    - google
                    - facebook
                    - github
                    - gitlab
                    - twitter
                    - linkedin
                    - microsoft
                  default: google
                callbackURL:
                  type: string
                  format: url
                  required: false
                  examples:
                    - https://better-auth.com
                  default: http://localhost:3000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: url
                  redirect:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Social Account is already linked.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                '$ref': '#/components/responses/Unauthorized'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Provider not found
  '/callback/:id':
    get:
      tags:
        - Callback
      summary: Callback
      descriptions: It's used to callback the social account.
      operationId: callback
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        id:
          name: id
          in: path
          required: true
          schema:
            type: string
        state:
          name: state
          in: query
          required: true
          schema:
            type: string
        code:
          name: code
          in: query
          required: false
          schema:
            type: string
        error:
          name: error
          in: query
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Redirect on error or success
  '/send-verification-email':
    post:
      tags:
        - Email Verification
      summary: Send verification email
      descriptions: It's used to send verification email.
      operationId: sendVerificationEmail
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        currentURL:
          name: currentURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  examples:
                    - bekacru@better-auth.com
                callbackURL:
                  type: string
                  format: url
                  required: false
                  examples:
                    - https://better-auth.com
                  default: http://localhost:3000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Verification email isn't enabled
                      - User not found
  '/verify-email':
    get:
      tags:
        - Email Verification
      summary: Verify email
      descriptions: It's used to verify email.
      operationId: verifyEmail
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        token:
          name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        callbackURL:
          name: callbackURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
            default: http://localhost:3000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
                    nullable: true
                  status:
                    type: boolean
                    examples:
                      - true
        '302':
          description: Redirect
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Invalid token
                      - User not found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Session not found
                      - Invalid session
  '/forget-password':
    post:
      tags:
        - Forget Password
      summary: Forget password
      descriptions: It's used to forget password.
      operationId: forgetPassword
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  examples:
                    - bekacru@better-auth.com
                redirctTo:
                  type: string
                  format: url
                  required: false
                  examples:
                    - https://better-auth.com
                  default: http://localhost:3000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Reset password isn't enabled
  '/reset-password/:token':
    get:
      tags:
        - Forget Password
      summary: Reset password with token
      descriptions: It's used to reset password with a token.
      operationId: resetPasswordToken
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        token:
          name: token
          in: path
          required: true
          schema:
            type: string
            format: uuid
        callbackURL:
          name: callbackURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
            default: http://localhost:3000
      responses:
        '302':
          description: Redirect
  '/reset-password':
    post:
      tags:
        - Forget Password
      summary: Reset password
      descriptions: It's used to reset/set a new password.
      operationId: resetPassword
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        token:
          name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        callbackURL:
          name: callbackURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newPassword:
                  type: string
                  examples:
                    - i-love-better-auth
                    - better-auth-is-cool
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Token not found
                      - Invalid token
                      - Failed to update password
  '/sign-in/social':
    post:
      tags:
        - Sign in
      summary: Sign in with social account
      descriptions: It's used to sign in with social account.
      operationId: signInSocial
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        currentURL:
          name: currentURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  examples:
                    - google
                    - facebook
                    - github
                    - gitlab
                    - twitter
                    - linkedin
                    - microsoft
                  default: google
                callbackURL:
                  type: string
                  format: url
                  required: false
                  examples:
                    - https://better-auth.com
                  default: http://localhost:3000
                idToken:
                  required: false
                  type: object
                  properties:
                    token:
                      type: string
                    nonce:
                      type: string
                      required: false
                    accessToken:
                      type: string
                      required: false
                    refreshToken:
                      type: string
                      required: false
                    expiresAt:
                      type: integer
                      format: int64
                      required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
                    nullable: true
                  session:
                    '$ref': '#/components/schemas/Session'
                    nullable: true
                  url:
                    type: string
                    format: url
                  redirect:
                    type: boolean
                    examples:
                      - true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Invalid id token
                      - Failed to get user info
                      - User email not found
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Provider not found
                      - Provider does not support id token verification
  '/sign-in/email':
    post:
      tags:
        - Sign in
      summary: Sign in with email
      descriptions: It's used to sign in with email.
      operationId: signInEmail
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  examples:
                    - bekacru@better-auth.com
                password:
                  type: string
                  examples:
                    - i-love-better-auth
                callbackURL:
                  type: string
                  format: url
                  required: false
                dontRememberMe:
                  type: boolean
                  examples:
                    - true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
                    nullable: true
                  session:
                    '$ref': '#/components/schemas/Session'
                    nullable: true
                  url:
                    type: string
                    format: url
                  redirect:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Invalid email
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Email and password is not enabled
                      - Invalid email or password
                      - Unexpected error
                      - Failed to create session
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Email is not verified. Check your email for a verification link
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Email is not verified.
  '/sign-out':
    post:
      tags:
        - Sign out
      summary: Sign out
      descriptions: It's used to sign out.
      operationId: signOut
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Session not found
  '/sign-up/email':
    post:
      tags:
        - Sign up
      summary: Sign up with email
      descriptions: It's used to sign up with email.
      operationId: signUpEmail
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        currentURL:
          name: currentURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  examples:
                    - Bekacru
                email:
                  type: string
                  format: email
                  examples:
                    - bekacru@better-auth.com
                password:
                  type: string
                  examples:
                    - i-love-better-auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
                  session:
                    '$ref': '#/components/schemas/Session'
                    nullable: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Email and password sign up is not enabled
                      - Invalid email
                      - Password is too short
                      - Password is too long
                      - Failed to create user
                      - Failed to create session
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - User with this email already exists
                      - Failed to create user
  '/update-user':
    post:
      tags:
        - Update user
      summary: Update user
      descriptions: It's used to update user.
      operationId: updateUser
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  required: false
                  type: string
                  examples:
                    - Bekacru
                image:
                  required: false
                  type: string
                  format: url
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - You can't update email
  '/change-password':
    post:
      tags:
        - Update user
      summary: Change password
      descriptions: It's used to change password.
      operationId: changePassword
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                currentPassword:
                  type: string
                  examples:
                    - i-like-better-auth
                newPassword:
                  type: string
                  examples:
                    - i-love-better-auth
                revokeOtherSessions:
                  type: boolean
                  examples:
                    - true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Password is too short
                      - Password too long
                      - User does not have a password
                      - Incorrect password
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unable to create session
  '/set-password':
    post:
      tags:
        - Update user
      summary: Set password
      descriptions: It's used to set password.
      operationId: setPassword
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newPassword:
                  type: string
                  examples:
                    - i-love-better-auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Password is too short
                      - Password too long
                      - user already has a password
  '/delete-user':
    post:
      tags:
        - Update user
      summary: Delete user
      descriptions: It's used to delete user.
      operationId: deleteUser
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  examples:
                    - i-love-better-auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: integer
                nullable: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - User does not have a password
                      - Incorrect password
  '/change-email':
    post:
      tags:
        - Update user
      summary: Change email
      descriptions: It's used to change email.
      operationId: changeEmail
      security:
        - bearerAuth: []
        - apiKeyCookie: []
      parameters:
        currentURL:
          name: currentURL
          in: query
          required: false
          schema:
            type: string
            format: url
            examples:
              - https://better-auth.com
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newEmail:
                  type: string
                  format: email
                  examples:
                    - bekacru@better-auth.com
                callbackURL:
                  type: string
                  format: url
                  required: false
                  examples:
                    - https://better-auth.com
                  default: http://localhost:3000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    '$ref': '#/components/schemas/User'
                    nullable: true
                  status:
                    type: boolean
                    examples:
                      - true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Change email is disabled
                      - Email is the same
                      - Couldn't update your email
                      - Verification email isn't enabled
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT Bearer token authentication
    apiKeyCookie:
      type: apiKey
      in: cookie
      name: api_key
      description: API key browser cookie
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            '$ref': '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            '$ref': '#/components/schemas/Error'
    NotFound:
      description: NotFound
      content:
        application/json:
          schema:
            '$ref': '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            '$ref': '#/components/schemas/Error'
  schemas:
    Session:
      type: object
      properties:
        session:
          type: object
          properties:
            id:
              type: string
            expiresAt:
              type: string
              format: date-time
            ipAddress:
              type: string
              format: ipv4
              example: 127.0.0.1
            userAgent:
              type: string
            userId:
              type: string
              format: uuid
        user:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            email:
              type: string
              format: email
            emailVerified:
              type: boolean
            image:
              type: string
              format: url
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    Account:
      type: object
      properties:
        id:
          type: string
        accountId:
          type: string
        providerId:
          type: string
          examples:
            - google
            - facebook
            - github
            - gitlab
            - twitter
            - linkedin
            - microsoft
        userId:
          type: string
        accessToken:
          type: string
        refreshToken:
          type: string
        idToken:
          type: string
        expiresAt:
          type: string
          format: date-time
        password:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        emailVerified:
          type: boolean
        image:
          type: string
          format: url
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807)
      properties:
        type:
          type: string
          examples:
            - https://example.com/errors/generic-error
        title:
          type: string
          examples:
            - Something went wrong here.
        status:
          type: integer
          format: int64
          examples:
            - 403
        detail:
          type: string
          examples:
            - Unfortunately, we can’t provide further information.