Incognia API

openapi: 3.1.0
info:
  title: Incognia API
  version: v2
  description: >-
    Incognia is a location identity and device fingerprinting platform for fraud
    prevention. The API returns real-time risk assessments (low_risk, high_risk,
    unknown_risk) for onboarding signups and authentication transactions (login
    and payment), and accepts feedback events used to continuously tune the risk
    model. Assessments combine device recognition signals, location behavior
    analysis, and tamper detection. Authentication uses OAuth 2.0 client
    credentials: a client_id and client_secret are exchanged at the token
    endpoint for a short-lived bearer access token.
  contact:
    name: Incognia Developer Support
    url: https://developer.incognia.com/
  x-source: >-
    Faithfully reconstructed from the official Incognia Go client library
    (github.com/inloco/incognia-go) endpoints, request and response types. Not a
    provider-published OpenAPI.
servers:
  - url: https://api.incognia.com/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth 2.0 client-credentials token exchange
  - name: Onboarding
    description: Signup risk assessment
  - name: Transactions
    description: Login and payment risk assessment
  - name: Feedback
    description: Report labeled events to tune the risk model
paths:
  /v2/token:
    post:
      operationId: createToken
      tags:
        - Authentication
      summary: Create an access token
      description: >-
        Exchange client_id and client_secret (sent via HTTP Basic auth) for a
        short-lived OAuth 2.0 bearer access token using the client_credentials
        grant. Send Content-Type application/x-www-form-urlencoded.
      security:
        - basicAuth: []
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: client_credentials
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          description: Missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/onboarding/signups:
    post:
      operationId: registerSignup
      tags:
        - Onboarding
      summary: Register a signup for risk assessment
      description: >-
        Evaluate a new-user onboarding signup and return a risk assessment. Send
        either an installation_id (mobile SDK) or a request_token (web), plus an
        optional address to assess address quality and location behavior.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '200':
          description: Signup risk assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupAssessment'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access token lacks permission for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/authentication/transactions:
    post:
      operationId: registerTransaction
      tags:
        - Transactions
      summary: Register a login or payment transaction for risk assessment
      description: >-
        Evaluate a login or payment transaction and return a risk assessment.
        Set type to "login" or "payment". Payment transactions may include
        payment_value, payment_methods and addresses; both accept an account_id
        to bind the assessment to a known user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '200':
          description: Transaction risk assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionAssessment'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access token lacks permission for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/feedbacks:
    post:
      operationId: registerFeedback
      tags:
        - Feedback
      summary: Register a feedback event
      description: >-
        Report a labeled event (for example account_takeover, chargeback,
        signup_accepted, payment_declined) tied to an assessment or account so
        Incognia can tune its risk model. Identify the subject with any of
        installation_id, request_token, login_id, payment_id, signup_id,
        account_id or external_id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
      responses:
        '200':
          description: Feedback accepted
        '400':
          description: Invalid feedback parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: client_id and client_secret sent as HTTP Basic credentials to the token endpoint.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer access token obtained from POST /v2/token.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client-credentials grant. No scopes are defined; access is scoped by the credential's tenant.
      flows:
        clientCredentials:
          tokenUrl: https://api.incognia.com/api/v2/token
          scopes: {}
  schemas:
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: string
          description: Token lifetime in seconds (string-encoded).
          example: '600'
        token_type:
          type: string
          example: Bearer
    Error:
      type: object
      description: Incognia error envelope.
      properties:
        message:
          type: string
          example: missing credentials
    Coordinates:
      type: object
      properties:
        lat:
          type: number
          format: double
        lng:
          type: number
          format: double
    StructuredAddress:
      type: object
      properties:
        locale: { type: string }
        country_name: { type: string }
        country_code: { type: string }
        state: { type: string }
        city: { type: string }
        county: { type: string }
        borough: { type: string }
        neighborhood: { type: string }
        street: { type: string }
        number: { type: string }
        complements: { type: string }
        postal_code: { type: string }
    Location:
      type: object
      properties:
        latitude: { type: number, format: double }
        longitude: { type: number, format: double }
        collected_at: { type: string, format: date-time }
    PersonID:
      type: object
      properties:
        type: { type: string }
        value: { type: string }
    PaymentValue:
      type: object
      properties:
        amount: { type: number, format: double }
        currency: { type: string }
    CardInfo:
      type: object
      properties:
        bin: { type: string }
        last_four_digits: { type: string }
        expiry_year: { type: string }
        expiry_month: { type: string }
    PaymentMethod:
      type: object
      properties:
        identifier: { type: string }
        type:
          type: string
          enum:
            - account_balance
            - apple_pay
            - bancolombia
            - boleto_bancario
            - cash
            - credit_card
            - credit_card_pos
            - debit_card
            - google_pay
            - meal_voucher
            - nu_pay
            - paypal
            - pix
            - pix_refund
            - tef
            - ted
        credit_card_info:
          $ref: '#/components/schemas/CardInfo'
        debit_card_info:
          $ref: '#/components/schemas/CardInfo'
        brand: { type: string }
    TransactionAddress:
      type: object
      properties:
        type:
          type: string
          enum: [shipping, billing, home]
        address_coordinates:
          $ref: '#/components/schemas/Coordinates'
        structured_address:
          $ref: '#/components/schemas/StructuredAddress'
        address_line: { type: string }
    Reason:
      type: object
      properties:
        code: { type: string }
        source: { type: string }
    RiskAssessment:
      type: string
      enum: [low_risk, high_risk, unknown_risk]
      description: Overall risk verdict returned by Incognia.
    SignupRequest:
      type: object
      properties:
        installation_id: { type: string }
        request_token: { type: string }
        related_web_request_token: { type: string }
        session_token: { type: string }
        app_version: { type: string }
        device_os: { type: string }
        address_line: { type: string }
        structured_address:
          $ref: '#/components/schemas/StructuredAddress'
        address_coordinates:
          $ref: '#/components/schemas/Coordinates'
        account_id: { type: string }
        policy_id: { type: string }
        external_id: { type: string }
        tenant_id: { type: string }
        custom_properties:
          type: object
          additionalProperties: true
        person_id:
          $ref: '#/components/schemas/PersonID'
    TransactionRequest:
      type: object
      required: [type, account_id]
      properties:
        type:
          type: string
          enum: [login, payment]
        account_id: { type: string }
        external_id: { type: string }
        tenant_id: { type: string }
        policy_id: { type: string }
        app_version: { type: string }
        device_os: { type: string }
        installation_id: { type: string }
        session_token: { type: string }
        request_token: { type: string }
        related_web_request_token: { type: string }
        store_id: { type: string }
        payment_method_identifier: { type: string }
        location:
          $ref: '#/components/schemas/Location'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/TransactionAddress'
        payment_value:
          $ref: '#/components/schemas/PaymentValue'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
        custom_properties:
          type: object
          additionalProperties: true
        person_id:
          $ref: '#/components/schemas/PersonID'
        countries:
          type: array
          items: { type: string }
    FeedbackRequest:
      type: object
      required: [event]
      properties:
        event:
          type: string
          description: The labeled feedback event.
          enum:
            - account_allowed
            - device_allowed
            - verified
            - reset
            - account_takeover
            - identity_fraud
            - chargeback
            - chargeback_notification
            - promotion_abuse
            - login_accepted
            - login_accepted_by_device_verification
            - login_accepted_by_facial_biometrics
            - login_accepted_by_manual_review
            - login_declined
            - login_declined_by_facial_biometrics
            - login_declined_by_manual_review
            - payment_accepted
            - payment_accepted_by_control_group
            - payment_accepted_by_third_party
            - payment_declined
            - payment_declined_by_acquirer
            - payment_declined_by_business
            - payment_declined_by_manual_review
            - payment_declined_by_risk_analysis
            - signup_accepted
            - signup_declined
        occurred_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        installation_id: { type: string }
        session_token: { type: string }
        request_token: { type: string }
        login_id: { type: string }
        payment_id: { type: string }
        signup_id: { type: string }
        account_id: { type: string }
        external_id: { type: string }
        person_id:
          $ref: '#/components/schemas/PersonID'
    SignupAssessment:
      type: object
      properties:
        id: { type: string }
        device_id: { type: string }
        request_id: { type: string }
        risk_assessment:
          $ref: '#/components/schemas/RiskAssessment'
        evidence:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        actions:
          type: array
          items: { type: string }
        signals:
          type: object
          additionalProperties: true
    TransactionAssessment:
      type: object
      properties:
        id: { type: string }
        risk_assessment:
          $ref: '#/components/schemas/RiskAssessment'
        device_id: { type: string }
        evidence:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        actions:
          type: array
          items: { type: string }
        signals:
          type: object
          additionalProperties: true