Skip to main content

Decide your architecture

As previously covered in the Introduction, Veriph.One's primary means of communication with your software is through two elements: 1) A Start Endpoint that your UI will trigger and 2) a Result Endpoint where we'll notify you of a verification result.

Due to the distinct nature of web and mobile apps, we recommend different implementations of these endpoints. However, the implementations overlap significantly, so they can coexist in the same API or share most of their code. Let's see what that means.

tip

Please read through this page before exploring the details of the two necessary endpoints. Deciding your architecture before moving forward is essential, especially for a mixed implementation.

Web implementation​

The primary purpose of the Start Endpoint is to secure and hide your API Key from others. As such, including your API Key or Secret in any client-side executable code is highly discouraged. But not less important, this endpoint will allow you to link any user, process, or transaction happening in your software to each verification flow you start on our platform.

Once your web app triggers the Start Endpoint, your server will obtain a single-use session that our SDK will use to verify your users' phone numbers. On the way back, our server will redirect the user to your Result Endpoint and expect it to redirect to your web app again based on the verification's result.

Veriph.One works similarly to OAuth2 in that we rely on a callback URL to return the result of the verification process to your app. This behavior means each API Key should have a distinct configuration on our dashboard. Please consider that the callback configuration only applies to web apps, and you cannot reuse keys across platforms. Moreover, each API Key only supports one callback URL, which entails a different configuration for each environment you use.

Let's see an example of how the callback works in a diagram:



  1. The client app (in this case, example.com) triggers the verification flow by passing the necessary information to an endpoint defined by its API or back end, usually through a GET request.
  2. The server (api.example.com) creates all the necessary ingredients for the phone verification process to start, then calls our API's create-session endpoint and, if successful, redirects the user to the Veriph.One app for it to take place.
  3. Once the user has finished the verification process or a validity status is available, Veriph.One redirects the user to the URL set by the client app (here, it could be example.com/verification-result, but it can be anything you'd like as long as it is capable of a GET request).
  4. With the query params received in the previous step, the client app's backend (not the frontend) calls an endpoint on our API called verification-result to get all the verification process details.
  5. Veriph.One's API, via verification-result, returns all of the information generated by the phone verification process.
  6. Example.com's backend then redirects the request to a user-friendly interface based on the result; for example, example.com/success in case of a successful verification.

We make continuous efforts to make our create-session and verification-result endpoints as fast and performant as possible because both processes need to be done as quickly as possible for two reasons:

  1. Your users will actively wait for the process to finish, and their browser will show that a URL is loading.
  2. The request can time out, and the user will receive a browser error that prompts a refresh, which might throw your app into an unexpected state.
danger

It might be tempting to use URLs in your front end as callbacks and endpoints and make the request to our API on your web app; avoid this at all costs. Doing so would expose your API Keys and application to data injection attacks and similar security vulnerabilities. Your server must be the source of truth in the verification process and should always be the authority determining the application flow.

Mobile implementation​

The behavior expected for mobile apps is almost identical to web apps, with only one exception: The endpoints shouldn't make any redirections but instead behave like old-fashioned (e.g., RESTful) web services that return a payload. The following diagram shows what it would look like:



  1. The client app (Android or iOS) triggers the verification flow by calling an endpoint defined by its API or back end.
  2. The server (api.example.com) creates all the necessary ingredients to start the phone verification process. It then calls our API's create-session endpoint and, if successful, returns the session UUID to the mobile app on the same request.
  3. The mobile app launches the SDK's UI using its credentials and the session UUID from step 2.
  4. Once the user has finished the verification process or a validity status is available, Veriph.One's SDK notifies the client app that a result is ready.
  5. The app then requests its server to determine how to proceed based on this session's result.
  6. Using the session's UUID, the backend calls an endpoint on our API called verification-result to get all the verification process details. Based on the result, it returns a response that the app can use to determine the next step on the user journey.
danger

It might be tempting to refrain from using your server as an intermediary to communicate with our API; we discourage you from doing so. In some cases, attackers can decompile your app or expose its internal data, granting them access to your server API Key and Secret. But, more importantly, this would expose your verification flow to data injection attacks and similar security vulnerabilities. Your server must be the source of truth in the verification process and should always be the authority determining the application flow.

Mixed implementation​

A mixed implementation is possible if your software offers web and mobile apps. It's simpler than it may seem, and there are many ways to do so; these are our top recommendations.

The best approach is to build independent web services for mobile and web that use the same underlying logic to reduce the implementation's code footprint. Let's use api.example.com to illustrate how this would work. We would need four endpoints in total:

  1. Two for Start Endpoint:
    1. api.example.com/verification/start/mobile
    2. api.example.com/verification/start/web
  2. Two for Result Endpoint:
    1. api.example.com/verification/result/mobile
    2. api.example.com/verification/result/web

The main differences between the mobile and web endpoints are:

  • Mobile Endpoints would:
    • Return a RESTful payload (or whichever architecture style you prefer) like a JSON, XML, or similar object.
    • Use GET, POST, PUT, or any HTTP method.
    • Be capable of returning any status code, including error states.
    • Require an API Key of type Generic Mobile, Android, or iOS.
  • Web Endpoints would:
    • Interact directly with the user's browser and rely on redirections.
    • Only use GET.
    • Limit the returning status code to 307.
    • Require an API Key of type Web.

Even with these differences, they don't need completely distinct implementations. Beyond these requirements, there are no additional restrictions, so they can share the underlying code used to link verifications to your processes and how you manage verification results.

info

We recommend this implementation because it is easier to test, less prone to bugs, and based on the 'separation of concerns' design principle without generating much overhead to your codebase.

Option 2: Reusable endpoints.​

Another possible approach is to use only one endpoint per use case for all platforms. In this scenario, api.example.com would only need two endpoints:

  1. One for Start Endpoint:
    1. api.example.com/verification/start?type={platform}
  2. One for Result Endpoint:
    1. api.example.com/verification/result?type={platform}

These endpoints would require some query parameter or leverage the HTTP method to define how to behave based on the platform interacting with it. In the case of mobile, they would act as a RESTful endpoint, but they would make a redirection if the platform is web. Meaning that these endpoints would need to meet these requirements:

  1. Ensure that Web clients can interact over GET and never return a code different from 307.
  2. Switch between Web and Mobile API Keys during execution depending on the platform interacting with the service.
  3. Make sure that Mobile apps can parse the server's response when requesting a new verification session and deciding what to do when it ends.
warning

This implementation might require the least amount of code necessary, but it needs thorough and rigorous testing to ensure that API Keys or responses are not mixed. Your verification flows might not work if they are, and users could become stuck.

Next steps​

Have you decided on your architecture and the platforms you'll be working with? Excellent, now it is time to build your endpoints. Click the button below to continue with the tutorial.

Do you have questions or need help understanding the implementation better? Contact us.