Mention Authentication

generated: '2026-08-13'
method: searched
source: >-
  https://dev.mention.com/current/src/index.html (Authentication),
  https://dev.mention.com/current/src/appendix/OAuth2.html,
  https://dev.mention.com/current/src/guidelines/Clients.html, and the securitySchemes in
  openapi/_original/mention-openapi.yml
docs: https://dev.mention.com/current/src/index.html
summary:
  types:
    - http
    - apiKey
    - oauth2
  api_key_in:
    - query
  oauth2_flows:
    - authorizationCode
  scopes: 0
  preferred: bearerAuth
  note: >-
    One credential, three ways to obtain or present it. Everything reduces to a bearer access token
    that carries full authority over one account; there are no scopes and no least-privilege option.

registration:
  required: true
  step: Create an API client (an "app") before any call.
  docs: https://dev.mention.com/current/src/guidelines/Clients.html
  note: >-
    "Registering will give you an access token that will be needed for your requests to the API."
    The token for your own account is printed at the bottom of the app's settings page. The same
    settings page holds the client_id and client_secret used by the OAuth2 flow, and the callback
    URLs that redirect_uri must be prefixed by.
  warning: >-
    Mention states the personal access token "gives full access to your account. Keep it
    confidential." It is not scoped and no rotation or expiry policy is documented.

schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    location: Authorization header
    format: 'Authorization: Bearer <access_token>'
    preferred: true
    description: >-
      The documented and preferred transport: "This is the preferred way to pass tokens, as it
      doesn't involve URL manipulations."
    example_request: |
      GET /api/accounts/me HTTP/1.1
      Host: api.mention.net
      Authorization: Bearer REDACTED_EXAMPLE_TOKEN
    sources:
      - openapi/_original/mention-openapi.yml
  - name: accessTokenQuery
    type: apiKey
    in: query
    parameter: access_token
    preferred: false
    description: >-
      The same token passed in the query string. Documented and supported, but discouraged by Mention
      itself — and it puts a full-authority credential into URLs, logs and referrers.
    example_request: 'GET /api/accounts/me?access_token=REDACTED_EXAMPLE_TOKEN'
    sources:
      - openapi/_original/mention-openapi.yml
  - name: oauth2
    type: oauth2
    description: >-
      Authorization-code flow used to obtain an access token for a third party's Mention account.
      Skip it entirely if you only need your own account — use the token on your app's settings page.
    flows:
      - flow: authorizationCode
        authorizationUrl: https://web.mention.com/authorize
        tokenUrl: https://web.mention.net/oauth/v2/token
        scopes: 0
    authorize_parameters:
      - name: client_id
        note: From the app's settings page.
      - name: redirect_uri
        note: Must be prefixed by one of the callback URLs registered on the app.
      - name: response_type
        note: code
    token_parameters:
      - name: client_id
      - name: client_secret
      - name: redirect_uri
        note: OAuth2 requires this to match the value used in the authorize step.
      - name: response_type
        note: Documented as "token" on the token exchange — a Mention-specific deviation; RFC 6749 defines no response_type on the token endpoint.
      - name: code
        note: The authorization code delivered to the callback in the query string.
      - name: grant_type
        note: authorization_code
    token_request:
      method: POST
      content_type: application/x-www-form-urlencoded
      note: >-
        GET is also accepted but explicitly discouraged. This is the only part of the API that is not
        JSON.
    token_response:
      shape: '{"access_token": "...", "token_type": "bearer"}'
      expires_in: not returned
      refresh_token: not returned
    sources:
      - openapi/_original/mention-openapi.yml

token_lifecycle:
  expiry: not documented
  refresh: not documented
  revocation: not documented
  rotation: not documented
  introspection: not documented
  note: >-
    No expires_in, no refresh_token grant, no revocation endpoint and no introspection endpoint
    appear anywhere in the reference. The only documented recovery from a rejected token is to
    re-read it from the app settings page or re-run the authorization flow.

discovery:
  rfc8414_metadata: false
  openid_configuration: false
  note: >-
    /.well-known/oauth-authorization-server and /.well-known/openid-configuration both return 404 on
    mention.com and api.mention.com. The endpoints are discoverable only by reading the prose docs.

failure_modes:
  - status: 401
    body: '{"error":"access_denied","error_description":"OAuth2 authentication required"}'
    observed:
      url: https://api.mention.net/api/accounts/me
      fetched: '2026-08-13'
    meaning: No token, malformed token, or token no longer valid.
  - status: 403
    meaning: >-
      Valid token, wrong subject. The reference repeats this rule for accounts and shares — a token
      cannot act on another person's account even when the app created it, and deleting someone
      else's share needs team-admin rights.
  - status: 402
    meaning: Valid token, but the account's plan does not cover the request or the parameter used.

agent_notes:
  - >-
    A Mention token is all-or-nothing. There is no read-only credential, so an agent holding one can
    delete accounts and delete shares — which destroys alerts and their collected mentions.
  - >-
    Constrain at the agent layer: see agentic-access/mention-agentic-access.yml for per-operation
    action-class, consequence and human-in-the-loop contracts.
  - Never use the access_token query parameter in an agent; it leaks a full-authority credential into logs.

cross_references:
  scopes: scopes/mention-scopes.yml
  conventions: conventions/mention-conventions.yml
  errors: errors/mention-problem-types.yml
  well_known: well-known/mention-well-known.yml
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com