mentio-dev Auth API

openapi: 3.2.0
info:
  title: Mentio Dev Auth API
  version: 0.0.1
  description: 'Operations tagged Auth across 4 of this provider''s published API definitions: api_mentio.json, mentio-dev-api-openapi.json, mentio-dev-app-openapi.json, mentio-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mentio.dev
tags:
- name: Auth
paths:
  /v1/whoami:
    get:
      operationId: whoami
      summary: Introspect the credential
      description: 'The workspace this credential acts on, how the request authenticated (an API key, an OAuth access token from an MCP sign-in, or the dashboard session), whether it may write, and for a key its id and expiry. Run it first: a read key answers 403 read_only_key on every write, and a wrong workspace is the classic scripting mistake.'
      tags:
      - Auth
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whoami'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.mentio.dev
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - read_only_key
              - validation_error
              - not_found
              - invalid_cursor
              - payload_too_large
              - rate_limited
              - duplicate_keyword
              - insufficient_balance
              - keyword_limit_reached
              - billing_not_configured
              - order_not_credited
              - schedule_required
              - unknown_channel
              - not_a_digest
              - hourly_email_unsupported
              - slack_not_connected
              - slack_not_configured
              - telegram_not_configured
              - feed_unreadable
              - feed_login_required
              - feed_login_expired
              - feed_limit_reached
              - feed_auth_not_configured
              - email_not_configured
              - invalid_assignee
              - classification_pending
              - invalid_member
              - already_member
              - last_owner
              - duplicate_segment
              - filter_too_complex
              - duplicate_view
              - duplicate_group
              - default_group
              - default_group_context
              - group_changed
              - invalid_signature
              - webhook_not_configured
              - invalid_token
              - protected_user
              - upstream_unavailable
              - internal_error
              description: 'Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.'
            message:
              type: string
              description: Human-readable detail; may change between releases.
            requestId:
              type: string
              description: The id of this request (also the X-Request-Id response header); quote it to support.
            retryAfterSeconds:
              type: integer
              description: 'For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).'
          required:
          - code
          - message
          description: The error.
      required:
      - error
    Whoami:
      type: object
      properties:
        workspace:
          type: object
          properties:
            id:
              type: string
              description: Workspace id (org_...).
            name:
              type: string
              description: The workspace name, as the dashboard shows it.
          required:
          - id
          - name
          description: The workspace this credential acts on.
        auth:
          type: object
          properties:
            kind:
              type: string
              enum:
              - api_key
              - oauth
              - session
              description: 'How the request authenticated: an API key, an OAuth access token (MCP sign-in), or the dashboard session.'
            scope:
              type: string
              enum:
              - read
              - write
              description: 'What the credential may do: read (GET only) or write.'
            apiKeyId:
              type:
              - string
              - 'null'
              description: The key id (key_...) when authenticated with an API key; null otherwise.
            expiresAt:
              type:
              - string
              - 'null'
              description: When an API key stops working; null for a key that never expires, an OAuth token or a session.
          required:
          - kind
          - scope
          - apiKeyId
          - expiresAt
          description: The credential.
        user:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              description: User id, what assigneeId and ownerId take.
            email:
              type: string
              description: The account's email address.
            name:
              type:
              - string
              - 'null'
              description: The name on the account; null when they never set one.
          required:
          - id
          - email
          - name
          description: The person behind an OAuth token or a session; null for an API key, which has no person behind it.
      required:
      - workspace
      - auth
      - user
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key minted via POST /v1/api-keys (format mk_live_...)
x-refined-from:
- api_mentio.json
- mentio-dev-api-openapi.json
- mentio-dev-app-openapi.json
- mentio-dev-openapi.json
x-mentio-errors:
- code: unauthorized
  status: 401
  source: user
  retryable: false
  description: No credential, or one that does not resolve to a workspace.
  fix: 'Send Authorization: Bearer mk_live_… with a key from /api-keys.'
- code: forbidden
  status: 403
  source: user
  retryable: false
  description: The credential is valid but may not do this.
- code: read_only_key
  status: 403
  source: user
  retryable: false
  description: A read key was used on a write endpoint.
  fix: Create a key with write scope.
- code: validation_error
  status: 400
  source: user
  retryable: false
  description: The body or query failed validation; the message names the field.
- code: not_found
  status: 404
  source: user
  retryable: false
  description: No such resource in your workspace. An id from another workspace is a 404, never a 403.
- code: invalid_cursor
  status: 400
  source: user
  retryable: false
  description: The cursor was not one this endpoint issued, or the filters changed between pages.
- code: payload_too_large
  status: 413
  source: user
  retryable: false
  description: The body exceeds the endpoint limit.
- code: rate_limited
  status: 429
  source: user
  retryable: true
  description: The workspace made more than 600 requests in a minute (every key and token together), or hit an endpoint's own cap; Retry-After says when.
  fix: Wait Retry-After seconds and send the same request again. X-RateLimit-Remaining on every response says how much room is left.
- code: duplicate_keyword
  status: 409
  source: user
  retryable: false
  description: The group already tracks this term. A term may be tracked once per group; another group may track it too.
- code: insufficient_balance
  status: 402
  source: user
  retryable: false
  description: The wallet cannot cover one more keyword-day.
  fix: Top up from Billing; tracking resumes on its own.
- code: keyword_limit_reached
  status: 402
  source: user
  retryable: false
  description: The self-serve keyword cap; beyond it is an enterprise conversation.
- code: billing_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no payment provider set up.
- code: schedule_required
  status: 400
  source: user
  retryable: false
  description: A daily alert rule was created without a schedule.
- code: unknown_channel
  status: 400
  source: user
  retryable: false
  description: A rule referenced a channel id the workspace does not own.
- code: not_a_digest
  status: 400
  source: user
  retryable: false
  description: A digest-only action was called on an instant rule.
- code: hourly_email_unsupported
  status: 400
  source: user
  retryable: false
  description: An hourly rule was given an email channel (up to 24 emails a day per rule). Use Slack, Telegram or a webhook, or a daily digest by email.
- code: slack_not_connected
  status: 409
  source: user
  retryable: false
  description: Connect Slack from Settings first. 404 on the Slack connection endpoints, 409 elsewhere.
- code: slack_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Slack app credentials.
- code: telegram_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Telegram bot.
- code: feed_unreadable
  status: 400
  source: user
  retryable: false
  description: No feed was found at the address, or the site blocks automated readers, or it answers an error; the message says which.
- code: feed_login_required
  status: 400
  source: user
  retryable: false
  description: The address answers a sign-in or access-denied page. Send it again with `auth` (the cookie your browser sends to the forum, or one header) to read it signed in.
- code: feed_login_expired
  status: 400
  source: user
  retryable: false
  description: 'The feed still answers a sign-in page with the `auth` sent: copy a fresh cookie from a signed-in browser.'
- code: feed_limit_reached
  status: 409
  source: user
  retryable: false
  description: A workspace reads at most 500 feeds; disconnect one before connecting another.
- code: feed_auth_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no FEED_AUTH_SECRET, so a feed sign-in (auth) cannot be stored encrypted and is refused instead.
- code: email_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Resend key, so nothing that needs Resend (the audience sync) can run.
- code: invalid_assignee
  status: 400
  source: user
  retryable: false
  description: The assignee id is not a workspace member.
- code: classification_pending
  status: 409
  source: user
  retryable: true
  description: A relevance or sentiment verdict was sent for a mention the classifier has not scored yet.
- code: invalid_member
  status: 400
  source: user
  retryable: false
  description: A person's owner, and the member an outreach activity is credited to, must be workspace members.
- code: already_member
  status: 409
  source: user
  retryable: false
  description: An invitation was sent to an address that already belongs to a member.
- code: last_owner
  status: 409
  source: user
  retryable: false
  description: Removing this member would leave the workspace without an owner.
- code: duplicate_segment
  status: 409
  source: user
  retryable: false
  description: Segment names are unique per workspace.
- code: filter_too_complex
  status: 400
  source: user
  retryable: false
  description: The filters together (lists, anyOf groups, a view or alert rule applied on top) name more values than one query can carry. Shorten the lists or use fewer groups.
- code: duplicate_view
  status: 409
  source: user
  retryable: false
  description: View names are unique per workspace.
- code: duplicate_group
  status: 409
  source: user
  retryable: false
  description: Group names and externalIds are unique per workspace.
- code: default_group
  status: 409
  source: user
  retryable: false
  description: Every workspace keeps one default group, where a keyword lands when no group is named.
- code: default_group_context
  status: 400
  source: user
  retryable: false
  description: 'The default group is the workspace itself: its company is the profile (PATCH /v1/company). A company description goes on any other group.'
- code: group_changed
  status: 409
  source: user
  retryable: false
  description: A keyword was created in or moved into the group while its keywords were being deleted. Its other keywords are gone; retry the delete.
- code: invalid_signature
  status: 401
  source: user
  retryable: false
  description: An inbound webhook did not carry a valid signature.
- code: webhook_not_configured
  status: 503
  source: system
  retryable: false
  description: The inbound webhook has no secret on this deployment.
- code: invalid_token
  status: 400
  source: user
  retryable: false
  description: A signed link (unsubscribe, confirmation) was tampered with or is malformed.
- code: protected_user
  status: 409
  source: user
  retryable: false
  description: Staff accounts cannot be deleted from the admin page.
- code: upstream_unavailable
  status: 502
  source: platform
  retryable: true
  description: A provider (Slack, Telegram, Polar, …) failed while serving your request. Retry with backoff.
- code: internal_error
  status: 500
  source: system
  retryable: false
  description: Something failed on our side. The response carries a requestId; quote it to support.