iProov User API

openapi: 3.2.0
info:
  title: Iproov User API
  version: 2.20.1
  contact:
    name: iProov API Team
  x-logo:
    url: logo.svg
    altText: iProov Logo
  description: 'Operations tagged User across 2 of this provider''s published API definitions: iproov-swagger.json, iproov-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://<base_url>/api/v2
  description: API Server
tags:
- name: User
  description: iProov user management APIs.
paths:
  /users/{existing_user_id}:
    get:
      tags:
      - User
      summary: Get a user's persona for a service provider
      operationId: userGet
      parameters:
      - name: existing_user_id
        in: path
        description: The asserted identifier of the user
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '403':
          description: Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - user-read
      x-redoc-order: 4
    put:
      tags:
      - User
      summary: Update a user's identifier for a service provider
      description: Update a user's identifier for a service provider. Note one (or both) of name and new user id is required.
      operationId: userUpdate
      parameters:
      - name: existing_user_id
        in: path
        description: The asserted identifier of the user
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request or Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '403':
          description: Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - user-write
      x-redoc-order: 3
    delete:
      tags:
      - User
      summary: Deletes a user's persona from a service provider
      operationId: userDelete
      parameters:
      - name: existing_user_id
        in: path
        description: The asserted identifier of the user
        required: true
        schema:
          type: string
          format: uuid
          example: c9d437ac-5a8d-4d05-9cf3-d61c6ae3aa57
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request or Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '403':
          description: Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCredentialErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
      security:
      - oauth2:
        - user-write
      x-redoc-order: 5
    servers:
    - url: https://<base_url>/api/v2
      description: API Server
components:
  schemas:
    ErrorResponse:
      description: The Error response contains an error constant which can be used to split up responses and can be converted to translatable error messages. The error description returns a more descriptive error response that is largely designed for developers to get detailed information for failures.
      required:
      - error
      - error_description
      properties:
        error:
          type: string
        error_description:
          type: string
      type: object
    ServerErrorResponse:
      description: Server Error
      required:
      - error
      - error_description
      properties:
        error:
          description: Generic iProov error code. If you receive this error code frequently please contact your customer success team or support@iproov.com.
          type: string
          enum:
          - server_error
        error_description:
          type: string
      type: object
    UpdateUserRequest:
      properties:
        user_id:
          description: The new identifier for the user
          type: string
        name:
          description: The name to display to the user when authenticating
          type: string
      type: object
    UserResponse:
      description: Contains a description of the user with User ID, Name, Status of the user, suspension and activated date.
      required:
      - user_id
      - name
      - status
      properties:
        user_id:
          type: string
          format: uuid
          example: c9d437ac-5a8d-4d05-9cf3-d61c6ae3aa57
        name:
          type: string
          example: John Doe
        status:
          description: A status of either 'inactive', 'active', 'suspended' or 'Deleted'.
          type: string
          example: active
        suspension_date:
          type: string
          format: date-time
          example: '2016-04-16T16:06:05Z'
        activation_date:
          type: string
          format: date-time
          example: '2016-05-16T16:06:05Z'
      type: object
    ClientErrorResponse:
      description: Missing data in the request, or the state of the requested entity object is such that the operation could not succeed.
      required:
      - error
      - error_description
      properties:
        error:
          description: "\n - `invalid_agent`: **DEPRECATED**.\n - `invalid_user_id`: Malformed, illegal characters in the user_id, missing, or non-existent user_id given.\n   - Regex: `[a-zA-Z0-9'\\+_@\\.-]{1,256}`.\n\n - `invalid_token`: An invalid token was provided in the body.\n   - Ensure the correct claim token is passed from the POST /claim/enrol/token or POST /claim/verify/token calls.\n   - Ensure the token is incorrectly reused. For an Enrol Capture call, once an image has been **registered** against a token, it cannot be called again.\n   - Attempted to validate a claim token that was previously validated.\n   - Attempted to validate a claim token before video imagery finished streaming.\n\n - `invalid_validation`: The username does not match the username associated with the claim token.\n   - Ensure the correct `user_id` is used.\n\n - `invalid_reason`: Malformed, illegal characters in `reason` parameter.\n   - Regex: `^[a-zA-Z0-9_.:=()'\\'\\\"/\\s]{1,800}$`.\n\n - `no_face_found`: No face found in enrolment image. Please try again with a photo with a face in it.\n - `invalid_grant`: Malformed, or missing `grant_type`. Correct the `grant_type` field.\n   - Regex: `^[a-zA-Z0-9_\\-.]{0,30}$`.\n\n - `invalid_request`: Malformed, or invalid IPv4 address given in `ip` field, or missing `grant_type` parameter.\n - `invalid_client`: Invalid, or missing basicAuth credentials for the given API key/Service Provider when requesting\n   OAuth `access_token`. Provide the correct credentials/API key - defined within your Service Provider. A key rotation\n   may have occurred.\n - `invalid_scope`: Malformed `scope` parameter in request.\n   - Regex: `^[a-zA-Z0-9_\\-.]{0,100}$`.\n\n - `unsupported_grant_type`: The request's `grant_type` parameter value is not `client_credentials`.\n - `missing_data`: Missing `resource`, `reason` or `token` parameter/value in request body.\n - `no_user`: The given `user_id` or username doesn't exist.\n - `inactive_user`: User is in the wrong state (should have an Active state). Ensure the user is not suspected (User management API).\n - `invalid_enrol_image`: Missing image attachment in multipart form data. Ensure the image is appended to the multipart form body correctly.\n - `invalid_source`: The `source` request parameter value must be one of `oid`, `eid` or `selfie`.\n - `already_enrolled`: The given username or `user_id` has already enrolled. Did you mean to conduct a verify transaction?\n   If a re-enrol is required, then either pass a new user_id or use the User Management API to delete the user and\n   request a new enrol claim token.\n - `invalid_key`: Missing or incorrect API Key. Check your API Key is correct:\n   1. Log into the iPortal.\n   2. Select your Service Provider.\n   3. Copy your API key.\n   4. Ensure your API Key and Secret are for the correct service provider\n"
          type: string
          enum:
          - invalid_agent
          - invalid_user_id
          - invalid_token
          - invalid_validation
          - invalid_reason
          - no_face_found
          - invalid_grant
          - invalid_request
          - invalid_client
          - invalid_scope
          - unsupported_grant_type
          - missing_data
          - no_user
          - inactive_user
          - invalid_enrol_image
          - invalid_source
          - already_enrolled
          - invalid_key
        error_description:
          type: string
      type: object
    InvalidCredentialErrorResponse:
      description: 'One of: invalid OAuth token, expired OAuth token, invalid credentials, API Key and/or Secret is missing, malformed, or incorrect.'
      required:
      - error
      - error_description
      properties:
        error:
          description: "\n - `invalid_key`: Missing or incorrect API Key. Check your API Key is correct:\n   1. Log into the iPortal.\n   2. Select your Service Provider.\n   3. Copy your API key.\n   4. Ensure your API Key and Secret are for the correct service provider\n - `invalid_oauth`: Missing OAuth `access_token`.\n   - Call POST /{api_key}/access_token to obtain a new OAuth Access token. Access tokens expire after 1 hr or 50 requests.\n - `invalid_token`: Invalid OAuth `access_token`.\n   - Call POST /{api_key}/access_token to obtain a new OAuth Access token. Access tokens expire after 1 hr or 50 requests.\n - `token_quota_exceeded`: 50/50 Oauth user requests used.\n   - Call POST /{api_key}/access_token to obtain a new OAuth Access token. Access tokens expire after 1 hr or 50 requests."
          type: string
          enum:
          - invalid_key
          - invalid_oauth
          - token_quota_exceeded
        error_description:
          type: string
      type: object
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 is used for the Management and User APIs.
      flows:
        clientCredentials:
          tokenUrl: /{api_key}/access_token
          scopes:
            user-write: Update the user object
            user-read: Read the information of users
    basicAuth:
      type: http
      description: These can now be obtained via the iPortal - OAuth Username and OAuth password.
      scheme: basic
x-refined-from:
- iproov-swagger.json
- iproov-openapi.yml
x-provenance:
  method: harvested
  publisher: iProov
  source: https://eu.rp.secure.iproov.me/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)