reach_five_identity_api.yaml

openapi: 3.0.0
servers:
  - url: https://YOUR_DOMAIN
    description: Server URL
tags:
  - name: Authentication
    description: |
      Some endpoints in the Identity API require an access token.

      Such tokens are obtained by calling [/oauth/token](#operation/retrieveAccessToken) endpoint.
      with your `client_id`, `client_secret`, `username`, and `password`.

      ```
      POST https://YOUR_DOMAIN/oauth/token
      {
        "grant_type": "password",
        "client_id": "CLIENT_ID",
        "client_secret": "CLIENT_SECRET",
        "username": "{{email}}",
        "password": "{{password}}",
        "scope": "{{space-separated list of scopes}}"
        "redirect_uri": "{{redirect_uri}}",
      }
      ```

      Required scopes are listed next to each endpoint.

      # Security Schemes

      <SecurityDefinitions>
  - name: Login/Signup
  - name: SSO
  - name: User Profile
  - name: Phone number
  - name: Email
  - name: MFA
    x-displayName: "Multi-factor Authentication"
    description: |
      Multi-factor Authentication (MFA) requires users to provide two or more verification factors to get access to a resource such as an application, online account, or when making a payment.
      It is an important component of a strong customer identity and access management policy particularly when payments are involved.

      > **The Step Up Flow**
      > - [startPhoneNumberRegistration](#operation/startPhoneNumberRegistration)
      > - [verifyPhoneNumberRegistration](#operation/verifyPhoneNumberRegistration)

      **OR**

      > - [startEmailRegistration](#operation/startEmailRegistration)
      > - [verifyEmailRegistration](#operation/verifyEmailRegistration)

      **THEN**

      > - [listCredentials](#operation/listCredentials) -- ensures MFA credentials are present on a user profile
      > - [stepup](#operation/stepup)
      > - [startPasswordlessFlow MFA](#operation/startPasswordlessFlow)
      > - [verifyPasswordlessPost MFA](#operation/verifyPasswordlessPost)
  - name: Password
  - name: Passwordless
  - name: FIDO
  - name: Events
  - name: Grants
    x-displayName: "Grants"
    description: |
      View and manage authorizations to third-party sites.

      **Note**: Users must be connected with a first-party access token. Otherwise, see the [Management API](https://developer.reachfive.com/api/management.html#tag/Grants).
  - name: AuthDescription
    x-displayName: "Overview"
    description: |-
      Some endpoints in the Identity API require an access token.

      Such tokens are obtained by calling [/oauth/token](#operation/retrieveAccessToken) endpoint.
      with your `client_id`, `client_secret`, `username`, and `password`.

      ```
      POST https://YOUR_DOMAIN/oauth/token
      {
        "grant_type": "password",
        "client_id": "CLIENT_ID",
        "client_secret": "CLIENT_SECRET",
        "username": "{{email}}",
        "password": "{{password}}",
        "scope": "{{space-separated list of scopes}}"
        "redirect_uri": "{{redirect_uri}}",
      }
      ```

      Required scopes are listed next to each endpoint.
x-tagGroups:
  - name: Authentication
    tags:
      - AuthDescription
      - OAuth
      - Login/Signup
      - Passwordless
      - FIDO2
      - MFA
  - name: User management
    tags:
      - Email
      - Grants
      - Password
      - Phone number
      - User Profile
  - name: Miscellaneous
    tags:
      - Events
info:
  description: |
    # Introduction
    Welcome to the documentation reference for the ReachFive REST Identity API!

    This API is documented in **OpenAPI standard**, and rendered using [ReDoc](https://github.com/Redocly/redoc).

    If something is missing, incorrect, or unclear, reach us at <documentation@reach5.co>.


    # Environment
    Endpoints are available at `https://{YOUR_DOMAIN}{ENDPOINT}`.

    Find how to obtain your ReachFive domain [here](https://developer.reachfive.com/docs/console.html#access-your-reachfive-console).

    # First and third-party clients

    Except if you want to implement OpenID as a Service (OaaS), **always** use first-party clients.

    In the context of OaaS, third-party clients are used to make calls to:

    - [/oauth/authorize](#operation/authorizeUser)
    - [/oauth/token](#operation/retrieveAccessToken)

    They **cannot** be used with other endpoints.

    If you to call any other endpoint with a third-party client, you will get this error:

    ```
    {
      "error_id": "9z8h7JmIHU",
      "error_description": "Not a first party identity client",
      "error_message_key": "error.client.notFirstParty",
      "error": "unauthorized_client",
      "error_user_msg": "Not a first party identity client"
    }
    ```

    # Errors

    The API uses standard HTTP status codes to indicate the success or failure of the API call.

    |Code   |Notes                                                                                           |
    |-------|------------------------------------------------------------------------------------------------|
    |`2xx`  | Success codes; indicates the request worked as expected.                                  |
    |`4xx`  | Error codes; indicates a client (user) error and more information is provided. See the example below.       |
    |`5xx`  | Server error codes; indicates an error with one of ReachFive's servers.                        |

    The error body is JSON and contains the following fields:

    ```
    {
        "error_id": "2hNBbvYecw",
        "error_description": "Invalid email or password",
        "error_message_key": "error.invalidEmailOrPassword",
        "error": "invalid_grant",
        "error_user_msg": "Invalid email or password"
    }
    ```

    - `error_id` is the auto-generated ID of the error.
    - `error_description` is the default error description.
    - `error_message_key` is the unique key that can be used to bind specific behaviors on other services. This also acts as the `i18n` translation key.
    - `error` is the error type. See the Error Types table below for more details.
    - `error_user_msg` is a user-friendly error message that should be used in the UI. This can be overriden in certain configurations.

    |Error Type|
    |----------|
    |`server_error`|
    |`invalid_request`|
    |`invalid_state`|
    |`invalid_grant`|
    |`invalid_scope`|
    |`insufficient_scope`|
    |`access_denied`|
    |`origin_not_allowed`|
    |`ip_address_not_allowed`|
    |`missing_config`|
    |`invalid_config`|
    |`resource_not_found`|
    |`temporarily_unavailable`|
    |`unsupported_grant_type`|
    |`unsupported_algorithm`|
    |`invalid_client`|
    |`unauthorized_client`|
    |`login_required`|
    |`email_already_exists`|
    |`external_id_already_exists`|
    |`phone_number_already_exists`|
    |`lite_profile_invalid_identifiers`|
    |`lite_profile_missing_profile`|
    |`password_too_weak`|
    |`rate_limit_reached`|
    |`webhook_host_unreachable`|
    |`webhook_invalid_response`|

    **Tip**: For more information, see the individual endpoints.

    # Security Schemes
    <SecurityDefinitions />
  version: "latest"
  title: ReachFive Identity API
  termsOfService: https://www.reachfive.com/terms-policies
  contact:
    name: Email
    email: documentation@reach5.co
    # url: http://www.reachfive.com/contact
  x-logo:
    url: _images/identity-api.png
    altText: OpenAPI Specification
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
# externalDocs:
#   description: Find out how to create Github repo for your OpenAPI spec.
#   url: https://github.com/Rebilly/generator-openapi-repo

# list of Identity Endpoints: https://app.asana.com/0/1142049698926411/1145782625194938 (as of 2.20)

paths:
  /oauth/revoke:
    post:
      summary: Revoke a token
      tags:
        - OAuth
      description: |
        Use this endpoint to invalidate (revoke) a refresh or access token.

        - **refresh_token**: When a refresh token is revoked, all the tokens associated with the user and `client_id` are revoked.
        - **access_token**: When an access token is revoked, only the tokens associated with the same specific grant are revoked.
      operationId: revokeToken
      requestBody:
        description: ""
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  description: Your client ID.
                  type: string
                  example: slNIt...yKzQM
                client_secret:
                  description: Your client Secret. Required if your Client's authorization method is POST.
                  type: string
                  example: dYEa3...3z2m2
                token:
                  description: |
                    The Token to revoke.

                    > **Note**: This can be either an `access_token` or a `refresh_token`.
                  type: string
                  example: XpcgV...5sSY5
                token_type_hint:
                  description: |
                    An optional string where you can hint at what type of token to differentiate between access and refresh.

                    > **Note**: The only meaningful values are `access_token` and `refresh_token`.
                  type: string
                  example: access_token
              required:
                - client_id
                - client_secret
                - token
      responses:
        "204":
          description: No Content.
      x-codeSamples:
        - lang: "cURL"
          source: |
            curl --request POST \
              --url https://DOMAIN/oauth/revoke \
              --header 'Content-Type: application/json' \
              --data '{
                  "client_id": "slNIt...yKzQM",
                  "client_secret": "dYEa3...3z2m2",
                  "token": "XpcgV...5sSY5"
            }'
  /identity/v1/send-email-verification:
    post:
      security:
        - OAuth2:
            - "none"
      summary: Request verification of the email address
      tags:
        - Email
      description: |
        Request the verification of the email address of a profile.
        If there is an email address configured in the profile that was not already verified, sends an email to verify it.

      operationId: sendEmailVerification
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/trueClientIp"
        - $ref: "#/components/parameters/trueClientIpKey"
        - $ref: "#/components/parameters/Custom-Locale"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                redirect_url:
                  description: The URL sent in the verification email to which the profile is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your ReachFive client settings.
                  type: string
                return_to_after_email_confirmation:
                  description: Returned in the `redirect_url` as a query parameter, this parameter is used as the post-email confirmation URL. It must be a valid URL.
                  type: string
      responses:
        "200":
          description: User receives an email to verify their email address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  verification_email_sent:
                    type: boolean
                    description: Whether the email was sent (`false` if the email address was already verified)
                example: { "verification_email_sent": true }
      x-codeSamples:
        - lang: "cURL"
          source: |
            curl --request POST \
              --url https://YOUR_DOMAIN/identity/v1/send-email-verification \
              --header 'Authorization: Bearer eyJ0eX...ll4Q2NT'
              --data '{
                "redirect_url": "https://example-email-verification.com"
            }'

components:
  responses:
    303redirect:
      description: |
        **Valid Code**: The user now begins a classic code or implicit flow from this point and is redirected to the specified `redirect_uri` with an access token.

        **Invalid Code**: The user is redirected to the specified `redirect_uri` where the error response is present as a *query parameter*. **Example**: `<redirect_uri>?error=invalid_grant&error_description=Invalid+Verification+Code&error_message_key=error.invalidVerificationCode`.
  parameters:
    Authorization:
      name: Authorization
      in: header
      schema:
        type: string
      required: true
      description: Bearer `{token}` for a valid OAuth token.
    access_token:
      name: Authorization
      in: header
      schema:
        type: string
      description: |
        Bearer `{access_token}` for a valid OAuth token. *(3)*

        > **Note**: The `access_token` is not required if you are passing the `tkn` as part of the request body or are using an active SSO session by passing the session cookie.
      example: 1pz032..32Ld0a
    fields:
      name: fields
      in: query
      description: |
        Fields to retrieve in the response.

        **Note**: See the [user profile object](https://developer.reachfive.com/docs/models-user-profile.html#the-user-profile-object) for a full list of fields to query.
      schema:
        type: array
        items:
          type: string
      explode: false
      example: [name, email, gender, emails.unverified] # https://github.com/Redocly/redoc/issues/1010
      allowReserved: true # https://github.com/Redocly/redoc/issues/1010
    Authorization_optional:
      name: Authorization
      in: header
      schema:
        type: string
      required: false
      description: Bearer `{token}` for a valid OAuth token.
    Custom-Locale:
      name: Custom-Locale
      in: header
      schema:
        type: string
      required: false
      description: |
        For any endpoint in this specification that generates an
        email or SMS, you can pass the Custom-Locale attribute as a header
        parameter.
      example: fr-FR
    trueClientIp:
      name: True-Client-IP
      in: header
      schema:
        type: string
      description: |
        An optional header field; IP to protect requests from the backend.

        **Note**: For more details, see [Identity Fraud Protection](https://developer.reachfive.com/docs/ifp.html#enable-true-client-ip-key).

      example: "224.136.62.167"
    trueClientIpKey:
      name: True-Client-IP-Key
      in: header
      schema:
        type: string
      description: |
        An optional header field; the secret that must match the True-Client-IP-Key generated in the ReachFive console.

        **Note**: For more details, see [Identity Fraud Protection](https://developer.reachfive.com/docs/ifp.html#enable-true-client-ip-key).

      example: "Isdaf03#@Rasdfj!j3jkl"