If you already run your own website, app or internal system, Spriv can add a second security check to it a tap on the user's phone, a text message reply, or a 6-digit code. This page explains what that looks like in everyday terms first, then gives your developer every endpoint, parameter, sample response and status code.
Today, someone signs into your system with a username and a password. If that password is stolen, guessed or reused from another site, whoever has it gets in. Spriv adds a second step that the thief almost certainly can't pass: proving they are holding the real user's phone.
Your system keeps doing what it already does. At the moment it would normally say "password correct, let them in," it asks Spriv first. Spriv contacts the user's phone, waits for an answer, and tells your system yes or no. Nothing about your existing login screen has to change.
On your own login page, exactly as they do now.
It sends us the username and a few details about the sign-in which computer, which browser, and the internet address it's coming from.
A familiar laptop in the usual office may be let through with no interruption. An unfamiliar device, or one in a different country an hour after the last sign-in, triggers a challenge.
They get a notification and tap Allow or Deny. Depending on how you configure it, this can instead be a text message they reply "YES" to, or a 6-digit code from the Spriv app.
Approved, denied, or still waiting. Your system lets the person in or stops them accordingly.
https://app.spriv.com · headers Content-Type: application/json, Accept: application/json, apiversion: 1 · spriv_key and spriv_secret in the body. Complete the Getting Started steps first, add each username, then pair it with a phone before calling any authentication endpoint.These calls keep Spriv's list of people in step with your own call them from wherever your system already creates, edits and removes accounts. The user's details are nested inside a user object.
In plain terms: registers a person with Spriv so they can be protected. Call it when a new account is created in your system.
Store the returned user_id the update, delete and pairing calls all need it.
POST https://app.spriv.com/manage_users
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"user": {
"email": "example@company.com",
"first_name": "joe",
"last_name": "doe",
"mobile_phone": "914444556677",
"person_id": "12277"
}
}
{
"user_id": 10,
"status": 200,
"message": "User created successfully."
}
In plain terms: changes someone's details most often a new phone number after they change handsets.
status_id in the response is the account's current state; status_timeout is how long a temporary state such as bypass still has left.PUT https://app.spriv.com/manage_users/<user id>
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"user": {
"email": "example@company.com",
"first_name": "joe",
"last_name": "doe",
"mobile_phone": "914444556677",
"person_id": "12277"
}
}
{
"status": 200,
"message": "User details updated successfully!",
"user": {
"id": 10,
"first_name": "joe",
"last_name": "doe",
"email": "example@company.com",
"person_id": "12277",
"mobile_phone": "914444556677",
"status_id": "bypass",
"status_timeout": null
}
}
In plain terms: removes someone from Spriv, for example when they leave the company. Their phone stops being able to approve sign-ins.
DELETE https://app.spriv.com/manage_users/<user id>
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key"
}
{
"status": 200,
"message": "User removed successfully."
}
In plain terms: emails the user a single-use link that ties their phone to their username. Nothing else on this page works until this is done.
Spriv sends a unique 32-bit URL to the user's email address. The user completes pairing in two clicks: open the link, then tap Pair. Spriv then sends a push notification to your callback URL, and from that moment the user can be authenticated. If the user is already paired, calling this endpoint unpairs them and sends a fresh pairing email.
The pairing link can be used only once. A second attempt with the same link returns "Invalid pairing code" see How pairing works.
POST https://app.spriv.com/manage_users/pair/<user id>
{
"spriv_key": "your spriv key",
"spriv_secret": "your spriv secret",
"email": "example@company.com",
"id": 83
}
These are the calls you make at the moment of login, once the password has already been accepted. Pick the one that matches the method you chose above you can use different methods for different groups of users.
Each of them can return an answer in one of two ways. Send "poll": true and you get back a poll_service_url to check repeatedly until the user answers; leave it out and Spriv contacts your callback URL instead. If you rely on the callback and haven't configured one, the API returns status 416.
In plain terms: asks Spriv to judge how risky this sign-in looks and challenge the user only when it's unusual. Once a user approves a given device, Spriv can approve later sign-ins from that same device automatically when it is near the paired phone.
true to receive a polling URL instead of a callback.POST https://app.spriv.com/authentication/adaptive_authentication
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"username": "username of user",
"os": "Windows 11",
"browser": "Chrome",
"computer_fingerprint": "user computer fingerprint",
"ip_address": "1.1.1.1",
"bypass_code": "your bypass code here",
"poll": true
}
// sent; decision arrives at your callback URL { "status": 200, "message": "User verification request sent." } // when "poll": true was sent { "status": 206, "message": "Sent Successfully; Pending Decision; Check URL for answer.", "poll_service_url": "https://app.spriv.com/poll/<polling id>" }
In plain terms: while the user is looking at their phone, your system asks Spriv every second or so whether they've answered yet. The same endpoint works for adaptive, allow/deny and SMS.
true on this endpoint.POST https://app.spriv.com/poll/<unique polling ID>
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"username": "username of user",
"poll": true
}
// approved let the user in { "status": 200, "message": 1 } // nothing matches this polling id treat as a failure { "status": 404, "message": "No matching transaction found." } // no answer yet wait and poll again { "status": 206, "message": "No response from mobile device yet. Please try again" }
In plain terms: always sends a notification to the phone, on every sign-in, with a custom message and two buttons. Best for admin accounts.
true to receive a polling URL instead of a callback.There is no option to automate Allow/Deny Authentication it always requires user action. That is deliberate: it is the strongest of the four methods.
POST https://app.spriv.com/authentication/allow_deny_authentication
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"totp": "742479",
"username": "your username",
"ip_address": "1.1.1.1",
"poll": true
}
{ "status": 200 }
// listen for a GET on /report_decision/
{
"decision": "1",
"transaction_id": "4C3EEA25CC20454CA7CEE929BCE50D94"
}
// no callback URL configured
{
"status": 416,
"errors": ["Callback URL not set. Please set it first."]
}
// when "poll": true was sent
{
"status": 206,
"message": "User verification request sent to device. Pending Decision. Check URL for answer.",
"poll_service_url": "https://app.spriv.com/poll/<polling id>"
}
In plain terms: texts the user a custom message and waits for them to reply YES. Use it for people who won't install an app.
There is no option to automate SMS requests each login sends a new message.
POST https://app.spriv.com/authentication/sms_authentication
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"username": "username of user",
"ip_address": "1.1.1.1",
"bypass_code": "your bypass code here"
}
// message sent, waiting on the reply { "status": 206, "message": "Verification SMS sent successfully." } // when "poll": true was sent { "poll_service_url": "https://app.spriv.com/poll/<polling id>", "status": 206, "message": "Sent Successfully; Pending Decision; Check URL for answer." } // the SMS could not be delivered { "status": 408, "errors": ["Unable to send SMS. Please try again later."] }
In plain terms: the user reads the 6-digit code from the Spriv app and types it into your login screen; you pass it here to be checked. It works on a phone with no signal it only needs battery. Combine it with any other method above for three-factor authentication.
POST https://app.spriv.com/authentication/totp
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"totp": "742479",
"username": "username of user"
}
// success { "status": 200, "user": { "id": 4, "first_name": "joe", "last_name": "doe", "email": "example@company.com", "mobile_phone": "914444556677", "status_id": "bypass", "status_timeout": 22 } } // wrong code { "status": 405, "errors": ["Incorrect OTP. Please try again"] } // unknown username { "status": 406, "errors": ["No such user found with this username"] }
Before a phone can be trusted, Spriv checks that the number really belongs to the user by texting a seven-digit code to it. The user types that code into your web page, and these two calls handle the check and the "I never got it" case.
In plain terms: the user types in the code they were texted, and you send it here to confirm the number is theirs.
POST https://app.spriv.com/manage_users/verify_phone_pin
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"user": {
"phone_pin": "phone pin number from sms",
"email": "example@company.com"
}
}
// success { "status": 200, "message": "Phone number verified successfully", "user": { "id": 11, /* … */ } } // wrong PIN { "status": 414, "errors": ["Wrong PIN number. Please enter correct one or resend SMS."] } // no user matches that email { "status": 415, "errors": ["Unable to find matching user. Please try again."] }
In plain terms: the text never arrived, or it expired. This cancels the previous code and sends a fresh one only the newest code will work.
POST https://app.spriv.com/manage_users/resend_phone_pin
{
"spriv_secret": "your spriv secret",
"spriv_key": "your spriv key",
"user": {
"email": "example@company.com"
}
}
{
"status": 200,
"message": "Phone pin sent successfully. Please check."
}
// no user matches that email
{
"status": 413,
"errors": ["Unable to find matching user. Please try again."]
}
These four aren't endpoints they're admin-configured settings from the control panel's "Company Settings" screen, and several of the status codes below come directly from them. Change them any time from that screen.
The FQDN or IP where Spriv sends push notifications, e.g. https://push.example.com/Adaptive/Two-factor-authentication.jsp. Leave it unset and every authentication call returns status 416 unless you send "poll": true.
435 for IPs off the list.419.417.422 (no paired device) instead of a hard failure.406 (no such user) would otherwise be returned.Every response carries a status. Anything other than 200 means the user was not authenticated treat it as a refusal, not a "maybe." Each row below gives the message Spriv returns and what to do about it.
/manage_users.resend_phone_pin when no user matches the email address.verify_phone_pin when no user matches the email address.verify_phone_pin before authenticating them.These aren't faults they're your administrator's rules being enforced. If one appears unexpectedly, check the company MFA settings above before assuming something is broken.
"poll": true and use the polling URL instead.spriv_key and spriv_secret don't belong together. Check this first when every call suddenly fails.417: the same code covers two unrelated situations an inactive, denied or locked account, and hitting the free-trial ceiling of two users and two servers. Read the message text, not just the number, before showing anything to the user.