> For the complete documentation index, see [llms.txt](https://docs.idlayr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idlayr.com/products/number-verification/secure-sna/integration/backend.md).

# Backend

{% hint style="info" %}
**Device API** · NV 1.0 · GA
{% endhint %}

The backend role in a Secure SNA integration: mint OAuth2 tokens, create the check, hand the verification URL to the device, and complete the check once the device returns the verification code.

## 1. Mint an access token

Exchange the project's `client_id` and `client_secret` for a short-lived access token.

```bash
curl -X POST https://{data_residency}.api.idlayr.com/oauth2/token \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials" \
  -d "scope=secure_sna"
```

Response:

```json
{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "secure_sna"
}
```

Tokens are short-lived (typically one hour). Cache the access token until it expires; request a new one before each expiry. See [Authentication](/get-started/authentication.md).

## 2. Create the check

POST the user's phone number to create a Secure SNA check.

```bash
curl -X POST https://{data_residency}.api.idlayr.com/v1/number-verification/secure-sna-checks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+447700900000",
    "callback_url": "https://your.app/callbacks/secure-sna",
    "redirect_url": "https://your.app/sna-return"
  }'
```

Request fields:

* `phone_number` — the MSISDN to verify, in E.164.
* `callback_url` *(optional)* — receives the terminal-status notification when the check reaches `COMPLETED`, `EXPIRED`, or `ERROR`.
* `redirect_url` *(optional)* — for browser-based flows. The device-side flow lands here at the end of the redirect chain, with the verification code in the query string.
* `reference_id` *(optional)* — your own identifier, echoed back on the response and any callback.

Response includes:

* `check_id` — needed to complete the check in step 4.
* `url` — the device-facing verification URL.
* `status` — initially `ACCEPTED`.
* `ttl` — seconds until the check expires if not completed.

## 3. Hand the verification URL to the device

Pass **only the `url`** to your iOS or Android app, over your own application API. The OAuth2 access token never leaves your backend — the SDK doesn't need it. See [iOS integration](/products/number-verification/secure-sna/integration/ios.md) or [Android integration](/products/number-verification/secure-sna/integration/android.md).

For browser-based flows, the device opens the `url` directly in a mobile browser; the user lands on your `redirect_url` with the verification code in the query string.

## 4. Complete the check

Once the device returns the verification code, redeem the code for the check via POST to resolve `match`:

```bash
curl -X POST https://{data_residency}.api.idlayr.com/v1/number-verification/secure-sna-checks/{check_id}/code \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"code": "{code}"}'
```

Response includes:

* `status` — `COMPLETED` if the check resolved, `EXPIRED` if the TTL passed before completion, `ERROR` for failures.
* `match` — `true` if the device's network-attached number matched the claimed number; `false` if it didn't. Only present when `status` is `COMPLETED`.
* `error_code` — present when `status` is `ERROR` or `EXPIRED`. See Error codes.
* `network_id` — present when `status` is `COMPLETED`.

## 5. Receive callbacks

If you supplied a `callback_url` in step 2, IDlayr POSTs the terminal-state SecureSNACheck to it when the check reaches a terminal status. The callback is signed via JWKS; verify the signature on your endpoint before trusting the payload.

See Callbacks for the signing model, delivery and retry behaviour, and the per-product event-shape reference.

## Production patterns

* **Cache access tokens** until they expire. Don't mint a fresh token per request.
* **Idempotency**: if a check creation request times out or fails before you record the `check_id`, you can't safely retry — you'll create a duplicate check. Use `reference_id` to correlate your side; consider a request-deduplication wrapper.
* **Sandbox vs production**: same endpoint, different project. To run both, create two projects (one sandbox, one production) with their own credentials.
* **Retries**: 5xx responses can be safely retried with exponential backoff. 4xx responses indicate a contract error — don't retry without changing the request.
* **Rate limits** apply on both the token endpoint and product endpoints. Cache tokens to stay under.
* **Verify callback signatures**: never trust a callback payload before verifying the JWKS signature. A device-side result is not authoritative until the backend has confirmed it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.idlayr.com/products/number-verification/secure-sna/integration/backend.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.