swagger: "2.0"
info: 
  description: "mParticle Identity API"
  title: "mParticle Identity API"
  version: "1.0"
schemes: 
  - https
host: identity.mparticle.com
basePath: /v1
paths: 
  /identify: 
    post: 
      consumes: 
        - application/json
      description: "mParticle identity endpoint - used to create and/or request an mParticle identity."
      parameters: 
        - $ref: "#/parameters/AuthHeaderKey"
        - $ref: "#/parameters/AuthHeaderDigest"
        - $ref: "#/parameters/AuthHeaderDate"
        - $ref: "#/parameters/IdentifyBodyRequest"
        - $ref: "#/parameters/ReadOnly"
        - $ref: "#/parameters/ReturnMatchedIds"
      produces: 
        - application/json
      responses: 
        200: 
          $ref: "#/responses/IdentifySuccessResponse"
        400: 
          $ref: "#/responses/BadRequest"
        401: 
          $ref: "#/responses/Unauthorized"
        429: 
          $ref: "#/responses/TooManyRequests"
          
  /login: 
    post: 
      consumes: 
        - application/json
      description: "mParticle identity endpoint - used to create and/or request an mParticle identity."
      parameters: 
        - $ref: "#/parameters/AuthHeaderKey"
        - $ref: "#/parameters/AuthHeaderDigest"
        - $ref: "#/parameters/AuthHeaderDate"
        - $ref: "#/parameters/IdentifyBodyRequest"
        - $ref: "#/parameters/ReadOnly"
        - $ref: "#/parameters/ReturnMatchedIds"
      produces: 
        - application/json
      responses: 
        200: 
          $ref: "#/responses/IdentifySuccessResponse"
        400: 
          $ref: "#/responses/BadRequest"
        401: 
          $ref: "#/responses/Unauthorized"
        429: 
          $ref: "#/responses/TooManyRequests"
          
  /logout: 
    post: 
      consumes: 
        - application/json
      description: "mParticle identity endpoint - used to create and/or request an mParticle identity."
      parameters: 
        - $ref: "#/parameters/AuthHeaderKey"
        - $ref: "#/parameters/AuthHeaderDigest"
        - $ref: "#/parameters/AuthHeaderDate"
        - $ref: "#/parameters/IdentifyBodyRequest"
        - $ref: "#/parameters/ReadOnly"
        - $ref: "#/parameters/ReturnMatchedIds"
      produces: 
        - application/json
      responses: 
        200: 
          $ref: "#/responses/IdentifySuccessResponse"
        400: 
          $ref: "#/responses/BadRequest"
        401: 
          $ref: "#/responses/Unauthorized"
        429: 
          $ref: "#/responses/TooManyRequests"
          
  /{mpid}/modify: 
    parameters:
       - $ref: "#/parameters/Mpid"
    post: 
      consumes: 
        - application/json
      description: "mParticle modify endpoint - used to modify an existing user."
      parameters: 
        - $ref: "#/parameters/AuthHeaderKey"
        - $ref: "#/parameters/AuthHeaderDigest"
        - $ref: "#/parameters/AuthHeaderDate"
        - $ref: "#/parameters/ModifyBodyRequest"
      produces: 
        - application/json
      responses: 
        200: 
          $ref: "#/responses/ModifySuccessResponse"
        400: 
          $ref: "#/responses/BadRequest"
        401: 
          $ref: "#/responses/Unauthorized"
        429: 
          $ref: "#/responses/TooManyRequests"
          
responses:
  IdentifySuccessResponse:
    description: "IdentifyResponse containing the newly created or updated MPID."
    schema: 
      $ref: "#/definitions/IdentifySuccessResponse"

  ModifySuccessResponse:
      description: "IdentifyResponse containing the newly created or updated MPID."
      schema: 
        $ref: "#/definitions/ModifySuccessResponse"
      
  BadRequest:
    description: "Bad request."
    schema: 
      $ref: "#/definitions/IdentityErrorResponse" 
      
  Unauthorized:
    description: "Unauthorized."
    
  TooManyRequests:
    description: "Too many requests. Reference Retry-After header and try again later."
    headers: 
      Retry-After: 
        description: "Seconds to wait before retrying the request."
        type: integer
        
securityDefinitions:
  BasicSecurity:
    type: basic
    description: "Basic authorization with your workspace API key and secret."
    
  ApiKeyDigest:
    type: apiKey
    in: header
    description: "API key digest auth - requires the x-mp-key, x-mp-signature, and Date headers."
    name: x-mp-key
    
security:
  - BasicSecurity: []
  - ApiKeyDigest: []
  
parameters:
  ReadOnly:
    name: read_only
    in: query
    description: Perform this action as a read-only operation for debugging purposes.
    required: false
    type: boolean
    
  Mpid:
    name: mpid
    in: path
    description: mParticle User Id
    required: true
    type: string
    
  AuthHeaderKey:
    name: x-mp-key
    in: header
    description: "API key for your mParticle workspace. REQUIRED for digest auth."
    type: string
    
  AuthHeaderDigest:
    name: x-mp-signature
    in: header
    description: "HMAC-SHA256 digest of the concatenated and newline separated: HTTP method, date, path, and request body. REQUIRED for digest auth."
    type: string
    
  AuthHeaderDate:
    description: "Current Date. REQUIRED for digest auth."
    in: header
    name: Date
    type: string
    
  IdentifyBodyRequest:
    description: "IdentifyRequest used to create and update an Identity in the mParticle platform."
    in: body
    name: body
    required: true
    schema: 
      $ref: "#/definitions/IdentifyRequest"  
      
  ModifyBodyRequest:
    description: "ModifyRequest used to modify an existing identity."
    in: body
    name: body
    required: true
    schema: 
      $ref: "#/definitions/ModifyRequest"    
      
  ReturnMatchedIds:
    name: return_matches
    in: query
    description: Return the IDs used to perform the look-up in the response body.
    required: false
    type: boolean
    
definitions: 
  IdentityBaseRequest:
    properties:
      client_sdk: 
        $ref: "#/definitions/ClientSdk"
      context: 
        description: "Previous context string."
        type: string
      environment: 
        description: "The environment to used to apply this change. (required)"
        enum: 
          - production
          - development
        type: string
      request_id: 
        type: string
      request_timestamp_ms:
        type: integer
    required: 
      - environment
    type: object
      
  IdentifyRequest: 
    type: object
    allOf: 
    - $ref: "#/definitions/IdentityBaseRequest"
    - type: object
      properties:
        previous_mpid: 
          type: string
        known_identities: 
          $ref: "#/definitions/Identities"
          
  ModifyRequest: 
    type: object
    allOf:
    - $ref: "#/definitions/IdentityBaseRequest"
    - type: object
      properties:
        identity_changes: 
          items: 
            $ref: "#/definitions/IdentityChange"
          type: array
      required: 
      - identity_changes
    
  IdentifySuccessResponse: 
    properties: 
      context: 
        description: "Base 64 string to store for the subsequent request."
        type: string
      matched_identities:
        $ref: "#/definitions/Identities"
      mpid: 
        description: "The mParticle ID associated with this Identity."
        type: string
      is_ephemeral: 
        description: "If true, the ID and its storage can be deleted by the client upon change of ID."
        readOnly: true
        type: boolean
    type: object

  ModifySuccessResponse: 
    type: object
    
  Platform: 
    enum:
      - ios
      - android
      - web
      - tvos
      - roku
      - alexa
      - smart_tv
      - fire
      - xbox
      - other
    type: string
    
  ClientSdk: 
    description: "Describes the client SDK originating the request."
    properties: 
      platform: 
        $ref: "#/definitions/Platform"
      sdk_vendor: 
        type: string
      sdk_version: 
        type: string
    type: object
    
  Identities: 
    additionalProperties: false
    properties: 
      ios_idfa: 
        type: string
        description: "iOS advertising ID"
      android_aaid: 
        type: string
        description: "Android advertising ID"
      amp_id: 
        type: string
        description: "Accelerated Mobile Pages (AMP) ID"
      android_uuid: 
        type: string
        description: "Legacy Android ID"
      ios_idfv: 
        type: string
        description: "iOS vendor ID"
      push_token: 
        type: string
        description: "iOS APNS push token, Android FCM Instance ID, or Fire push token"
      roku_publisher_id: 
        type: string
        description: "Roku publisher ID"
      roku_aid: 
        type: string        
        description: "Roku advertising ID"
      customerid: 
        type: string
      email: 
        type: string
      facebook: 
        type: string
      facebookcustomaudienceid: 
        type: string
      google: 
        type: string
      microsoft: 
        type: string
      other:
        type: string
      twitter: 
        type: string
      yahoo: 
        type: string
      device_application_stamp: 
        type: string
    type: object
  
  IdentityChange:
    type: object
    required: [old_value, new_value, identity_type]
    properties:
      old_value:
        type: string
        description: "The previous value that was associated with this identity type, or null if this is a new id."
      new_value:
        type: string
        description: "The new value to associate with this identity_type, or null to remove the value."
      identity_type: 
        type: string
        enum: 
          - ios_idfa
          - android_aaid
          - amp_id
          - android_uuid
          - ios_idfv
          - push_token
          - roku_publisher_id
          - roku_aid
          - customerid
          - email
          - facebook
          - facebookcustomaudienceid
          - google
          - microsoft
          - other
          - twitter
          - yahoo
    
  IdentityErrorResponse: 
    description: "Indicates one or more errors occured during the request."
    properties: 
      errors: 
        items: 
          properties: 
            code: 
              type: string
            message: 
              type: string
          type: object
        type: array
    type: object