generated: '2026-09-18'
method: searched
source: https://docs.apinity.io/step-by-step/subscribe-and-consume-a-service/consume-an-api-technical-implementation
docs:
  - https://docs.apinity.io/concepts/authorization
  - https://docs.apinity.io/step-by-step/subscribe-and-consume-a-service/consumer-clients
  - https://docs.apinity.io/step-by-step/provide-a-service-on-the-marketplace/add-an-api
provider: Apinity.io
providerId: apinity-io
description: >-
  Authentication profile of the apinity marketplace gateway (the Kong-based engine that fronts every
  service sold on an apinity tenant, e.g. apinity Xplore). There is no OpenAPI for the gateway itself;
  this profile is read from the end-user documentation. Every request carries the CONSUMER CLIENT
  token obtained from a per-subscription /login endpoint; the upstream provider's own credential, when
  the provider chose pass-through authorization, travels in the ordinary Authorization header alongside it.
gateway_base: https://api.marketplace.apinity.io/{EndpointURI}
gateway_base_note: >-
  {EndpointURI} is unique per subscription and shown under Subscriptions > Technical Setup in the portal
  (the docs' example is hello-world/639041ec-a6ba-4684-b37e-10677d482eb7). Probed 2026-09-18 the host
  presents a *.apinity.io certificate that does not cover this two-level subdomain, so the documented
  base cannot be reached over verified TLS; no live probe of the login flow was possible.
schemes:
  - id: consumerClientApiKey
    type: apiKey
    in: header
    name: x-apx-authorization
    flow: >-
      POST {gateway_base}/login with JSON body {"api-key": "<key>"} (Content-Type: application/json).
      A 200 returns {"expires_in": <seconds>, "access_token": "Basic ..."}; send that value verbatim in the
      x-apx-authorization header on every subsequent call.
    token_lifetime: 31536000 seconds (exactly one year); repeat login calls inside the window return the same token; ending the subscription invalidates it
    credential_issuance: API key generated when a Consumer Client of type API-Key is created in My Hub; shown once, cannot be retrieved later, can be regenerated
    docs: https://docs.apinity.io/step-by-step/subscribe-and-consume-a-service/consume-an-api-technical-implementation#consumeanapi-technicalimplementation-accessapiandauthenticationwithanapikey
  - id: consumerClientOAuth2
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://api.marketplace.apinity.io/{EndpointURI}/login
        refreshUrl: https://api.marketplace.apinity.io/{EndpointURI}/login
        scopes: {}
    flow: >-
      POST {gateway_base}/login as application/x-www-form-urlencoded with grant_type=client_credentials,
      client_id, client_secret. Returns access_token ("Bearer eyJ..."), refresh_token, expires_in (300 in the
      docs' example) and refresh_token_expires_in (1800). Refresh with grant_type=refresh_token to the same
      endpoint. The access token is sent in the x-apx-authorization header.
    scopes_note: no API scopes are documented; the example JWT carries the OIDC default scope "profile email" and is issued by the Keycloak realm below
    issuer: https://auth.apinity.io/realms/syncier-marketplace-engine
    discovery: well-known/apinity-io-openid-configuration.json
    credential_issuance: Client ID + Client Secret generated when a Consumer Client of type OAuth2 is created; the secret is shown once and can be regenerated; the type cannot be changed after creation
    docs: https://docs.apinity.io/step-by-step/subscribe-and-consume-a-service/consume-an-api-technical-implementation#consumeanapi-technicalimplementation-accessapiandauthenticationwithoauth2
  - id: providerPassThrough
    type: http
    scheme: provider-defined
    in: header
    name: Authorization
    description: >-
      Optional second credential. When a service provider did not configure an Access Control on the
      gateway, subscribers send the provider's own credential in the Authorization header; the gateway
      forwards the request unmodified. When an Access Control IS configured, the gateway strips/replaces
      the Authorization header with the provider-side credential it holds (Basic, API-key header,
      username/password header, OAuth2 password or client-credentials, HMAC, auth-key header, JSON payload).
    docs: https://docs.apinity.io/concepts/authorization#2b.-pass-through-authorization
header_notes:
  - The consumer token may be sent in Authorization instead of x-apx-authorization only when the provider does not need Authorization for pass-through; the gateway consumes it either way.
  - Since the October 2023 release x-apx-authorization is the canonical header; pre-existing subscriptions that send the gateway token in Authorization keep working.
failure_modes:
  - status: 401
    when: x-apx-authorization header absent — the gateway rejects before forwarding upstream
  - status: 403
    when: header present but the token is invalid — also rejected at the gateway
  - status: 404
    when: the request URL omits the https:// prefix