Bevz Authentication

generated: '2026-08-13'
method: searched
source: https://docs.bevz.com/#tag/Getting-Started
docs: https://docs.bevz.com/
spec: openapi/bevz-integrator-service-openapi.yaml
api: Bevz Integrator Service
summary: >-
  Bevz protects the Integrator Service with a bearer JWT that an integrator mints from its own
  email/password credentials. Credentials are not self-serve: Bevz issues sandbox credentials during
  the development phase and production credentials only after a collaborative sign-off.
schemes:
  - id: bearer-jwt
    type: http
    scheme: bearer
    bearer_format: JWT
    location: header
    header: Authorization
    value_format: 'Bearer <token>'
    description: >-
      Every Integrator Service operation requires the Authorization header. The published docs state
      plainly: "Ensure you include the header: Authorization: Bearer yourJWTtoken in every request."
    required: true
token:
  issuance:
    endpoint: POST {baseUrl}/integrators/login
    request_fields: [email, password]
    response_path: data.token
    documented_at: https://docs.bevz.com/#tag/Getting-Started
    note: >-
      The login endpoint is documented in prose and in the quickstart cURL sample but is NOT declared
      in the OpenAPI paths object — a client cannot discover it from the machine-readable contract.
  lifetime_days: 30
  renewal: Log in again to mint a new token. No refresh-token flow is published.
  claims:
    source: openapi/_original/yaml/schemas/jwt.yaml
    fields:
      - {name: id, description: Integrator user identifier.}
      - {name: email, description: Integrator user email.}
      - {name: client, description: 'Caller class. Published enumeration: Integrator | Portal | Retailer.'}
      - {name: scope, description: Scope claim carried in the JWT. Bevz publishes no scope vocabulary and the documented sample carries "*".}
      - {name: aud, description: 'Audience. Observed value in the published sample: Bevz.'}
      - {name: exp, description: Expiry, consistent with the documented 30-day lifetime.}
    algorithm_note: The published sample token header declares HS256, but Bevz does not document the signing algorithm as a contract, and no JWKS endpoint is published.
oauth2:
  applies_to_bevz_api: false
  note: >-
    Bevz itself does not expose OAuth. OAuth 2.0 appears only as a THIRD-PARTY flow the API brokers:
    generateOAuth / exchangeCode / provisionStore drive the Uber Eats merchant authorization
    handshake on the store's behalf, and their 400 responses surface Uber Eats OAuth errors
    (invalid_client, invalid_grant, invalid_request, invalid_scope, access_denied).
onboarding:
  self_serve: false
  process: >-
    Email support@bevz.com to request an Integrator account; an Integrator Account Manager runs
    onboarding. Bevz then provides sandbox credentials plus a required-API checklist, and issues
    production credentials only after collaborative testing and sign-off.
  source: https://docs.bevz.com/#tag/faq
authorization:
  model: tenant-scoped
  description: >-
    Authorization is enforced by integrator tenancy, not by scopes. Every path is nested under
    /integrators/{integrator_id}, and the published errors confirm the boundary is checked:
    "Integrator unauthorized to perform this action!" (401) and "Unable to access store, can only
    update store within the Integrator's umbrella" (400).
  scopes_published: false
  roles_published: false
  edge: >-
    The API is fronted by AWS API Gateway. Unauthenticated requests to the host return
    {"message":"Forbidden"} or {"message":"Missing Authentication Token"} with HTTP 403, and the
    spec's shared 403 body is "User is not authorized to access this resource with an explicit deny"
    — the API Gateway authorizer's own wording.
errors:
  - {status: 401, meaning: JWT missing, expired or invalid., remediation: Re-authenticate at POST /integrators/login. Tokens older than 30 days are rejected.}
  - {status: 403, meaning: Gateway authorizer explicit deny., remediation: Confirm the integrator identity is entitled to the resource; contact tech@bevz.com.}
gaps:
  - >-
    The OpenAPI declares NO components.securitySchemes and no security requirement on any of its 30
    operations. Authentication is modeled as a required `Authorization` header PARAMETER on each
    operation instead, so generated clients and scanners will read this contract as unauthenticated
    even though every call needs a bearer token. This is the single highest-value fix available on
    this contract.
  - The token-minting endpoint (POST /integrators/login) is absent from paths[].
  - No JWKS / OIDC discovery document, no /.well-known/openid-configuration, and no published signing algorithm contract.
  - No scope vocabulary, despite the JWT carrying a scope claim.
  - No token revocation endpoint and no refresh flow are published.