samva-dev Whoami API

openapi: 3.2.0
info:
  title: Samva Whoami API
  version: 1.0.0
  description: Samva is the email API for your app. Send transactional email in one typed call. Delivery events and customer replies come back as signed webhooks, and replies thread to the email they answer.
servers:
- url: https://api.samva.dev
security: []
tags:
- name: Whoami
  description: The organization and credential behind the request.
paths:
  /v1/whoami:
    get:
      tags:
      - Whoami
      operationId: whoami.get
      parameters: []
      security:
      - apiKey: []
      responses:
        '200':
          description: Whoami
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whoami'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          description: ValidationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: 'Returns the organization the request acts in and the credential it presents: an API key with its name, prefix, and access, or a signed-in user with their role. Any valid credential may call it, whatever its grants.'
      summary: Get the calling credential
components:
  schemas:
    ValidationError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ValidationError
        message:
          type: string
        fields:
          anyOf:
          - type: object
            additionalProperties:
              type: array
              items:
                type: string
          - type: 'null'
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - validation
      x-retryable: false
    NamespaceId:
      type: string
      pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: NamespaceId
    ApiKeyMailboxAccess:
      type: object
      properties:
        permissions:
          type: array
          prefixItems:
          - type: string
            enum:
            - read
            - update
            - send
            - quarantine.read
          minItems: 1
          items:
            type: string
            enum:
            - read
            - update
            - send
            - quarantine.read
          description: '`read` reads mailboxes, threads, and messages; `update` changes thread state, labels, drafts, and notes; `send` sends and replies; `quarantine.read` reads quarantined mail.'
        mailboxIds:
          anyOf:
          - type: array
            prefixItems:
            - $ref: '#/components/schemas/MailboxId'
            minItems: 1
            items:
              $ref: '#/components/schemas/MailboxId'
          - type: 'null'
          description: The mailboxes the key may act on. Omit to reach every mailbox the owner can.
        sendMode:
          anyOf:
          - $ref: '#/components/schemas/MailboxSendMode'
          - type: 'null'
          description: Defaults to `send`. With `approval`, each send waits until a person other than the key approves it.
      required:
      - permissions
      additionalProperties: false
    GatewayTimeoutError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - GatewayTimeoutError
        message:
          type: string
        retryAfterSeconds:
          type: number
      required:
      - _tag
      - message
      - retryAfterSeconds
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    OrganizationId:
      type: string
      pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: OrganizationId
    WhoamiUser:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
      required:
      - id
      - name
      - email
      additionalProperties: false
    MailboxId:
      type: string
      pattern: ^mbx_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: MailboxId
    MailboxSendMode:
      type: string
      enum:
      - send
      - approval
      description: 'How the grantee''s sends execute: `send` runs them within account limits; `approval` holds each one until a different member approves it.'
    WhoamiOrganization:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/OrganizationId'
        slug:
          type: string
        name:
          type: string
      required:
      - id
      - slug
      - name
      additionalProperties: false
    UnauthorizedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - UnauthorizedError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    WhoamiUserCredential:
      type: object
      properties:
        type:
          type: string
          enum:
          - user
        user:
          $ref: '#/components/schemas/WhoamiUser'
        role:
          type: string
          enum:
          - mail_user
          - member
          - admin
          - owner
      required:
      - type
      - user
      - role
      additionalProperties: false
    ApiKeyAccess:
      anyOf:
      - type: object
        properties:
          mode:
            type: string
            enum:
            - full
        required:
        - mode
        additionalProperties: false
      - type: object
        properties:
          mode:
            type: string
            enum:
            - restricted
          resources:
            $ref: '#/components/schemas/ApiKeyResourceAccess'
          mailboxes:
            anyOf:
            - $ref: '#/components/schemas/ApiKeyMailboxAccess'
            - type: 'null'
          namespaceId:
            anyOf:
            - $ref: '#/components/schemas/NamespaceId'
            - type: 'null'
            description: 'Confines the key to one namespace: it reaches only that namespace''s domains, senders, numbers, mailboxes, contacts, templates, and messages, never organization-level ones, and only endpoints that confine to a namespace (others answer 403). It holds grants only on `mailboxes`, `messages`, `email`, `domains`, `contacts`, and `templates`. A key scoped to listed mailboxes holds mailbox access only.'
        required:
        - mode
        - resources
        additionalProperties: false
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    Whoami:
      type: object
      properties:
        organization:
          $ref: '#/components/schemas/WhoamiOrganization'
        credential:
          anyOf:
          - $ref: '#/components/schemas/WhoamiApiKeyCredential'
          - $ref: '#/components/schemas/WhoamiUserCredential'
      required:
      - organization
      - credential
      additionalProperties: false
    InternalError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - InternalError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    ApiKeyResourceAccess:
      type: object
      properties:
        messages:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        email:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        domains:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        phoneNumbers:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        contacts:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        conversations:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        templates:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        agents:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        webhooks:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        apiKeys:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        organization:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        billing:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
        analytics:
          anyOf:
          - type: string
            enum:
            - read
            - write
          - type: 'null'
      additionalProperties: false
    WhoamiApiKeyCredential:
      type: object
      properties:
        type:
          type: string
          enum:
          - apiKey
        id:
          type: string
        name:
          type: string
        start:
          anyOf:
          - type: string
          - type: 'null'
        access:
          $ref: '#/components/schemas/ApiKeyAccess'
      required:
      - type
      - id
      - name
      - start
      - access
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header