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.
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:
- 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.
- The server (
api.example.com
) creates all the necessary ingredients for the phone verification process to start, then calls our API'screate-session
endpoint and, if successful, redirects the user to the Veriph.One app for it to take place. - 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). - 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. - Veriph.One's API, via
verification-result
, returns all of the information generated by the phone verification process. - 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:
- Your users will actively wait for the process to finish, and their browser will show that a URL is loading.
- 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.
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.