openapi: 3.2.0
info:
  title: Gr4vy Sessions API
  version: 1.1.0-beta
  contact:
    name: Gr4vy Support
    email: code@gr4vy.com
    url: https://gr4vy.com
  termsOfService: https://gr4vy.com
  license:
    name: MIT
    url: https://raw.githubusercontent.com/gr4vy/gr4vy-openapi/main/LICENSE
  description: 'Welcome to the Gr4vy API reference documentation.

    Our API is still very much a work in product and subject to change.'
servers:
- url: https://api.sandbox.{id}.gr4vy.app
  x-speakeasy-server-id: sandbox
  variables:
    id:
      default: example
      description: The subdomain for your Gr4vy instance.
- url: https://api.{id}.gr4vy.app
  x-speakeasy-server-id: production
  variables:
    id:
      default: example
      description: The subdomain for your Gr4vy instance.
security:
- bearerAuth: []
tags:
- name: Sessions
  description: 'The sessions APIs are used to facilitate user authentication for the Gr4vy

    dashboard.'
  x-internal: true
paths:
  /auth/sessions:
    post:
      operationId: login
      summary: Login user
      description: Authenticate a user.
      tags:
      - Sessions
      x-internal: true
      x-speakeasy-ignore: true
      security: []
      requestBody:
        content:
          application/json:
            schema:
              x-model-name: SessionRequest
              oneOf:
              - $ref: '#/components/schemas/SessionRequestEmailAndPassword'
              - $ref: '#/components/schemas/SessionRequestToken'
      responses:
        '200':
          description: Returns a session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: Returns an error if the request was badly formatted or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400BadRequest'
        '401':
          description: Returns an error if the credentials provided were not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '403':
          description: Returns an error if the access to the requested resource is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403Forbidden'
        '409':
          description: Returns an error if duplicate resource has been found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409DuplicateRecord'
    put:
      operationId: refresh-session
      summary: Refresh user session
      description: Re-authenticate a user using a refresh token.
      tags:
      - Sessions
      x-internal: true
      x-speakeasy-ignore: true
      responses:
        '200':
          description: Returns a session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: Returns an error if the request was badly formatted or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400BadRequest'
        '401':
          description: Returns an error if the refresh token provided was not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
    delete:
      operationId: logout
      summary: Logout user
      description: Ends a user's session by invalidating the used access token.
      tags:
      - Sessions
      x-internal: true
      x-speakeasy-ignore: true
      responses:
        '204':
          description: Returns an empty response.
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
components:
  schemas:
    Session:
      title: Session
      description: A user session.
      type: object
      x-tags:
      - Authentication
      x-internal: true
      properties:
        type:
          type: string
          example: auth.session
          description: '`auth.session`.'
          enum:
          - auth.session
        token_type:
          type: string
          enum:
          - bearer
          example: bearer
          description: '`bearer`.'
        access_token:
          type: string
          description: 'A server-signed JWT that can be used as the bearer token in any

            API calls.'
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
        refresh_token:
          type: string
          description: 'A server-signed JWT that can be used as the bearer token to refresh the

            access token.'
          example: nJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ3FIOG9vSGV4VHo4QzAyg5T1JvNc
        expires_in:
          type: integer
          format: int64
          example: 3600
          description: 'The time in seconds in seconds by which the `access_token` token will

            expire.'
    Error403Forbidden:
      title: Forbidden Error
      type: object
      description: Forbidden Error (HTTP 403).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: '`forbidden`.'
          example: forbidden
          enum:
          - forbidden
        status:
          type: integer
          description: '`403`.'
          example: 403
          enum:
          - 403
        message:
          type: string
          description: Invalid credentials.
          example: Invalid credentials
          enum:
          - Invalid credentials
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      title: Error details
      description: Additional detail about the part of a request body that caused an issue.
      type: object
      x-tags:
      - Errors
      properties:
        location:
          type: string
          example: body
          description: The location where the error caused an issue.
          enum:
          - query
          - body
          - path
          - header
        type:
          type: string
          example: value_error.missing
          description: A unique identifier for the type of error that occurred.
        pointer:
          type: string
          example: /payment_method/number
          description: 'The exact item for which the validation did not succeed. This is a JSON

            pointer for request bodies, while for query, path, and header parameters

            it is the name of the parameter.'
        message:
          type: string
          example: field required
          description: A human readable message for this error detail.
    Error409DuplicateRecord:
      title: Duplicate Record Error
      type: object
      description: Duplicate Record Error (HTTP 409).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: '`duplicate_record`.'
          example: duplicate_record
          enum:
          - duplicate_record
        status:
          type: integer
          description: '`409`.'
          example: 409
          enum:
          - 409
        message:
          type: string
          description: Further details on the field that triggered the error.
          example: A duplicate record exists with this external_identifier value
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    SessionRequestToken:
      title: Token session
      type: object
      description: A request to create a session using an ID token.
      x-internal: true
      x-tags:
      - Authentication
      required:
      - token
      properties:
        token:
          type: string
          description: The Google ID token.
          example: XYZ123
    Error401Unauthorized:
      title: Unauthorized Error
      type: object
      description: Unauthorized Error (HTTP 401).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: '`unauthorized`.'
          example: unauthorized
          enum:
          - unauthorized
        status:
          type: integer
          description: '`401`.'
          example: 401
          enum:
          - 401
        message:
          type: string
          description: No valid API authentication found.
          example: No valid API authentication found
          enum:
          - No valid API authentication found
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    Error400BadRequest:
      title: Bad Request
      type: object
      description: Bad Request (HTTP 400).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: A short code that describes the reason for the error.
          example: bad_request
          enum:
          - bad_request
          - incorrect_json
          - invalid_credentials
        status:
          type: integer
          description: '`400`.'
          example: 400
          enum:
          - 400
        message:
          type: string
          description: A human-readable reason for the error.
          example: Missing '****' field
        details:
          type: array
          description: A list of detail objects that further clarify the reason for the error.
          items:
            $ref: '#/components/schemas/ErrorDetail'
    SessionRequestEmailAndPassword:
      title: Username/password session
      type: object
      description: A request to create a session using an email address and password.
      x-internal: true
      x-tags:
      - Authentication
      required:
      - email_address
      - password
      properties:
        email_address:
          type: string
          description: The email address of the user to log in as.
          example: john@example.com
        password:
          type: string
          description: The password the user to log in as.
          example: this-is-n0t-a-secure-passw0rd
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT