Verify Push API

Verify Push endpoints exposed by the Devotel CPaaS API Base path: /api/v1/verify/push Endpoint count: 4

Verify a push challenge signature

POST /api/v1/verify/push/challenges/{challengeId}/verify

Verify the device’s signature over the challenge’s signing string. On match: challenge moves to approved, factor flips to verified. On mismatch: attempts increment; auto-denied at maxAttempts.

challengeId

string

required

—

signature

string

required

The device’s base64-encoded signature over the challenge signing string factorId.challengeId.nonce (1–4096 characters).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify", headers=headers, json={
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify", bytes.NewBuffer([]byte(`{
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/push/challenges/{challengeId}/verify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "signature": "c2lnbmF0dXJlX2Jhc2U2NF9wbGFjZWhvbGRlcl9kZW1vX29ubHlfbm90X2FfcmVhbF9zaWduYXR1cmVfdmFsdWU="
}
JSON);
echo curl_exec($ch);

Register a push factor

POST /api/v1/verify/push/factors

Register a device’s public key for phishing-resistant MFA. Returns a binding challenge the device must sign to activate the factor.

identity

string

required

Stable identifier for the end user this device belongs to — your user id, email, or username (1–255 characters).

friendlyName

string

required

Human-readable label for the paired device, shown when the user reviews their registered factors (1–120 characters).

algorithm

string (enum: ed25519|ecdsa-p256)

required

Signature algorithm of the device key pair — ed25519 or ecdsa-p256.

publicKey

string

required

The device’s base64-encoded public key. The matching private key never leaves the device; it signs each challenge (1–4096 characters).

keyFormat

string (enum: raw|spki)

required

Encoding of publicKey — raw for a bare key or spki for a SubjectPublicKeyInfo-wrapped key.

deviceTokenId

string

Optional push-token id (FCM, APNs, or Web Push) the service uses to deliver challenge notifications to this device (1–120 characters).

metadata

object

Optional free-form key/value bag — device model, OS version, attestation chain. The caller defines the contract.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/factors" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/push/factors', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/push/factors", headers=headers, json={
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/push/factors", bytes.NewBuffer([]byte(`{
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/push/factors')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/push/factors');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "identity": "user_1a2b3c",
  "friendlyName": "iPhone 15 Pro",
  "algorithm": "ed25519",
  "publicKey": "3Mv6c0kZ8y2Qb7pL9dWfX1aRtH4sN6uG0eI2oJ5PqE=",
  "keyFormat": "raw",
  "deviceTokenId": "fcm_e8b1c2d3a4f5",
  "metadata": {
    "deviceModel": "iPhone15,3",
    "os": "iOS 17.4"
  }
}
JSON);
echo curl_exec($ch);

Issue a push challenge

POST /api/v1/verify/push/factors/{factorId}/challenges

Mint a server-issued nonce + persist a pending challenge row. The device signs <factorId>.<challengeId>.<nonce> and submits the signature via /verify/push/challenges/:challengeId/verify.

factorId

string

required

—

contextMessage

string

Human-readable prompt shown in the push notification so the user knows what they are approving, e.g. the action or device (1–280 characters).

ttlSeconds

integer

Lifetime of the issued challenge, in seconds, before it expires. Defaults to 120; range 30–600.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges", headers=headers, json={
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges", bytes.NewBuffer([]byte(`{
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/challenges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "contextMessage": "Approve sign-in from Chrome on macOS",
  "ttlSeconds": 120
}
JSON);
echo curl_exec($ch);

Revoke a push factor

POST /api/v1/verify/push/factors/{factorId}/revoke

Mark a factor as revoked. All subsequent challenges are rejected with a 409 + reason=FACTOR_REVOKED. Irreversible.

factorId

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/push/factors/{factorId}/revoke');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

API Reference

All Endpoints

Verify Push API

Verify Push API

Verify a push challenge signature

Register a push factor

Issue a push challenge

Revoke a push factor

​Verify Push API

​Verify a push challenge signature

​Register a push factor

​Issue a push challenge

​Revoke a push factor

Verify Push API

Verify a push challenge signature

Register a push factor

Issue a push challenge

Revoke a push factor