Prelude

https://docs.prelude.so
Admin
Prelude is a suite of powerful APIs for phone and email verification, messaging, phone number...
Tokens:855,600
Snippets:4,613
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Go example for List Users

Source: https://docs.prelude.so/auth/api-reference/management/users/list-users

Uses net/http to send a GET request with a Bearer token and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Initiate SAML login (explicit connection) - GET request examples

Source: https://docs.prelude.so/session/api-reference/frontend/saml-initiate

Example requests for the Initiate SAML login (explicit connection) endpoint. All use GET to the same URL and return a JSON response with a redirect_url. The cURL example is the canonical request; the others are equivalent client implementations.

```bash
curl --request GET \
  --url https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate
```

```python
import requests

url = "https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate"

response = requests.get(url)

print(response.text)
```

```javascript
const options = {method: 'GET'};

fetch('https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://changeme.session.prelude.dev/v1/session/login/saml/{provider_id}/{connection_id}/initiate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

--------------------------------

### Go request to get step-up config

Source: https://docs.prelude.so/auth/api-reference/management/config/stepup/get-stepup-config

Go example using net/http to fetch the step-up configuration. Replace {appID} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/stepup"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go example to retrieve a message template

Source: https://docs.prelude.so/notify/v2/api-reference/management/templates/get-template

Uses net/http to send a GET request with an Authorization header. Reads and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/notify/management/templates/{template_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get a flow with Go net/http

Source: https://docs.prelude.so/watch/v2/api-reference/management/flows/get-flow

Go example using net/http to fetch a flow. Replace {flow_id} and <token> with your values.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/watch/management/flows/{flow_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby example for List Users

Source: https://docs.prelude.so/auth/api-reference/management/users/list-users

Uses net/http to send a GET request with SSL and a Bearer token, then prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/session/apps/{appID}/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Ruby request to get step-up config

Source: https://docs.prelude.so/auth/api-reference/management/config/stepup/get-stepup-config

Ruby example using net/http to fetch the step-up configuration. Replace {appID} and <token> as needed.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/session/apps/{appID}/config/stepup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Go example for listing subscription phone numbers

Source: https://docs.prelude.so/notify/v2/api-reference/management/subscriptions/list-subscription-phone-numbers

Uses the net/http package to send a GET request with a bearer token and prints the response body.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/notify/management/subscriptions/{config_id}/phone_numbers?limit=50"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Install Prelude SDKs

Source: https://docs.prelude.so/verify/v2/documentation/quickstart

Install the Prelude backend SDK for Node.js, Python, Go, and Java (Gradle and Maven).

```bash
npm add @prelude.so/sdk
```

```bash
pip install prelude_python_sdk
```

```bash
go get github.com/prelude-so/go-sdk
```

```groovy
implementation("so.prelude.sdk:prelude-java:0.2.0")
```

```xml
<dependency>
    <groupId>so.prelude.sdk</groupId>
    <artifactId>prelude-java</artifactId>
    <version>0.2.0</version>
</dependency>
```

--------------------------------

### Get migration config - request examples

Source: https://docs.prelude.so/auth/api-reference/management/config/migration/get-migration-config

Example requests for the GET /v2/session/apps/{appID}/config/migration endpoint in cURL, Python, JavaScript, PHP, Go, Java, and Ruby. All use the same URL and Bearer token authorization header.

```bash
curl --request GET \
  --url https://api.prelude.dev/v2/session/apps/{appID}/config/migration \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.prelude.dev/v2/session/apps/{appID}/config/migration"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/session/apps/{appID}/config/migration', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/session/apps/{appID}/config/migration",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/migration"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.prelude.dev/v2/session/apps/{appID}/config/migration")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/session/apps/{appID}/config/migration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Go example for creating claims mapping

Source: https://docs.prelude.so/auth/api-reference/management/config/claims/create-claims-mapping

Go example using net/http to POST a claims mapping configuration. Replace {appID} and <token> with your values.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/claims"

	payload := strings.NewReader("{\n  \"mapping\": {\n    \"custom_claim\": \"profile.first_name\",\n    \"role\": \"profile.role\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get SAML connection - request examples

Source: https://docs.prelude.so/auth/api-reference/management/config/login-saml/get-saml-connection

Example requests for the GET /v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID} endpoint in cURL, Python, JavaScript, PHP, Go, Java, and Ruby. All use the Authorization header with a Bearer token.

```bash
curl --request GET \
  --url https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID} \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### List subscription configurations - GET /v2/notify/management/subscriptions

Source: https://docs.prelude.so/notify/v2/api-reference/management/subscriptions/list-subscription-configs

Example requests to list subscription configurations using the GET /v2/notify/management/subscriptions endpoint. Each example uses the required Authorization header with a Bearer token and the optional limit query parameter set to 50.

```cURL
curl --request GET \
  --url 'https://api.prelude.dev/v2/notify/management/subscriptions?limit=50' \
  --header 'Authorization: Bearer <token>'
```

```Python
import requests

url = "https://api.prelude.dev/v2/notify/management/subscriptions?limit=50"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```JavaScript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/notify/management/subscriptions?limit=50', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/notify/management/subscriptions?limit=50",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/notify/management/subscriptions?limit=50"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```Java
HttpResponse<String> response = Unirest.get("https://api.prelude.dev/v2/notify/management/subscriptions?limit=50")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/notify/management/subscriptions?limit=50")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Go example for creating a domain

Source: https://docs.prelude.so/auth/api-reference/management/domains/create-domain

Uses net/http to send a POST request with a JSON string body. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/domains"

	payload := strings.NewReader("{\n  \"domain\": \"session.example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### GET /v2/verification/phone/history/{id}

Source: https://docs.prelude.so/verify/v2/api-reference/history/get-a-phone-verification

This snippet documents the GET endpoint for retrieving a phone verification's history, including its response fields and example requests in multiple languages.

```APIDOC
## GET /v2/verification/phone/history/{id}

### Description
Retrieves the details of a phone verification, including its status, conditions, signals, and lifecycle timeline.

### Method
GET

### Endpoint
https://api.prelude.dev/v2/verification/phone/history/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the phone verification.

### Authentication
Bearer token required in the Authorization header.

### Request Example
```
curl --request GET \
  --url https://api.prelude.dev/v2/verification/phone/history/{id} \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **automation_signature** (enum) - Indicates if the verification was flagged for automation signature.
- **carrier_not_permitted** (enum) - Indicates if the carrier was not permitted.
- **client_fingerprint_mismatch** (enum) - Indicates if the client fingerprint mismatched.
- **custom_policy** (enum) - Indicates if a custom policy was triggered.
- **device_emulator** (enum) - Indicates if a device emulator was detected.
- **device_not_permitted** (enum) - Indicates if the device was not permitted.
- **device_reuse** (enum) - Indicates if the device was reused.
- **expired_signals** (enum) - Indicates if the signals expired.
- **fraud_database** (enum) - Indicates if the verification matched a fraud database.
- **invalid_signature** (enum) - Indicates if the signature was invalid.
- **ip_concentration** (enum) - Indicates if there was IP concentration.
- **ip_reputation** (enum) - Indicates the IP reputation.
- **location_mismatch** (enum) - Indicates if there was a location mismatch.
- **missing_signals** (enum) - Indicates if signals were missing.
- **number_range_abuse** (enum) - Indicates if the number range was abused.
- **poor_conversion_history** (enum) - Indicates if there was poor conversion history.
- **proxy_network** (enum) - Indicates if a proxy network was detected.
- **repeated_attempts** (enum) - Indicates if there were repeated attempts.
- **temporary_phone_number** (enum) - Indicates if a temporary phone number was used.
- **phone_number_condition** (enum) - Whether the phone number was allow-listed, block-listed, or sandboxed at verification time.
- **phone_number_current_condition** (enum) - Whether the phone number is currently allow-listed, block-listed, or sandboxed.
- **signals_hash_status** (enum) - Whether the SDK signals integrity check passed.
- **correlation_id** (string) - The correlation identifier you supplied when creating the verification.
- **template_id** (string) - The template used for this verification.
- **lifecycle** (object) - Chronological timeline of the verification: creation, message attempts with delivery events, code checks and signals reception. Omitted when Prelude holds no timeline for the verification.
- **signals** (object) - The anti-fraud signals you forwarded when creating the verification.

#### Response Example
```json
{
  "automation_signature": "...",
  "carrier_not_permitted": "...",
  "client_fingerprint_mismatch": "...",
  "custom_policy": "...",
  "device_emulator": "...",
  "device_not_permitted": "...",
  "device_reuse": "...",
  "expired_signals": "...",
  "fraud_database": "...",
  "invalid_signature": "...",
  "ip_concentration": "...",
  "ip_reputation": "...",
  "location_mismatch": "...",
  "missing_signals": "...",
  "number_range_abuse": "...",
  "poor_conversion_history": "...",
  "proxy_network": "...",
  "repeated_attempts": "...",
  "temporary_phone_number": "...",
  "phone_number_condition": "...",
  "phone_number_current_condition": "...",
  "signals_hash_status": "...",
  "correlation_id": "...",
  "template_id": "...",
  "lifecycle": {},
  "signals": {}
}
```
```

--------------------------------

### Go example for creating OTP login config

Source: https://docs.prelude.so/auth/api-reference/management/config/login-otp/create-login-otp-config

Uses net/http to POST the OTP config with a JSON string body. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/login/otp"

	payload := strings.NewReader("{\n  \"config_type\": \"otp\",\n  \"channel_type\": \"sms\",\n  \"template_id\": \"tpl_01jqebhswje1ka1z7ahr9rfsgt\",\n  \"sender_id\": \"Prelude\",\n  \"is_default\": false,\n  \"granted_scopes\": [\n    \"prld:pwd:write\"\n  ],\n  \"code_size\": 6\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### 200 Response for Get user

Source: https://docs.prelude.so/auth/api-reference/management/users/get-user

Example 200 response for the Get user endpoint. Contains the user object with id, status, identifiers, scopes, profile, timestamps, and external_id.

```json
{
  "user": {
    "id": "usr_01jqebhswje1ka1z7ahr9rfsgt",
    "status": "active",
    "identifiers": [
      {
        "type": "phone_number",
        "value": "+306912345678"
      }
    ],
    "scopes": [
      "premium",
      "admin"
    ],
    "profile": {
      "first_name": "John",
      "last_name": "Doe",
      "locales": [
        "en-US"
      ]
    },
    "created_at": "2025-03-15T10:30:00Z",
    "updated_at": "2025-03-15T12:00:00Z",
    "external_id": "customer-user-42"
  }
}
```

--------------------------------

### Install the Prelude JavaScript SDK with npm

Source: https://docs.prelude.so/auth/documentation/frontend-sdks/web

Install the @prelude.so/js-sdk package in your frontend project using npm.

```bash
npm install @prelude.so/js-sdk

```

--------------------------------

### Subscription webhook event examples (STOP, START, HELP)

Source: https://docs.prelude.so/notify/v2/documentation/webhook

Example webhook payloads for subscription events. Each event includes the event ID, type, payload with action, sender, destination, and timestamps. The STOP event indicates the user opted out, START indicates opt-in, and HELP indicates a help request.

```json
{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "marketing.subscription.stop",
  "payload": {
    "action": "STOP",
    "from": "+33612345678",
    "to": "36184",
    "received_at": "2025-10-24T08:59:10.736909995Z"
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}
```

```json
{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "marketing.subscription.start",
  "payload": {
    "action": "START",
    "from": "+33612345678",
    "to": "36184",
    "received_at": "2025-10-24T08:59:10.736909995Z"
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}
```

```json
{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "marketing.subscription.help",
  "payload": {
    "action": "HELP",
    "from": "+33612345678",
    "to": "36184",
    "received_at": "2025-10-24T08:59:10.736909995Z"
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}
```

--------------------------------

### Start OAuth flow with initiate()

Source: https://docs.prelude.so/auth/documentation/integration-guide/sso

Starts the OAuth flow by calling initiate() to get the authorization URL and then navigating the browser to it. The PKCE verifier and state are persisted automatically; initiate() does not navigate.

```javascript
const { authorizationURL } = await oauth.initiate();
window.location.href = authorizationURL;

```

--------------------------------

### Go HTTP request to initiate SAML login

Source: https://docs.prelude.so/auth/api-reference/frontend/saml-initiate-by-email

Go example using the standard net/http package to send a GET request to the SAML initiate endpoint and print the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://changeme.session.prelude.dev/v1/session/login/saml/initiate"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get SAML connection - 200 response

Source: https://docs.prelude.so/auth/api-reference/management/config/login-saml/get-saml-connection

Example 200 response body for the Get SAML connection endpoint. Contains the full connection object with id, provider_id, name, enabled, idp, sp, behavior, mapping, and timestamps.

```json
{
  "connection": {
    "id": "samlc_01jqebhswje1ka1z7ahr9rfsgt",
    "provider_id": "okta",
    "name": "Acme Okta",
    "enabled": true,
    "idp": {
      "entity_id": "http://www.okta.com/exk1fcia6d6EMsf331d8",
      "sso_url": "https://acme.okta.com/app/abc/exk.../sso/saml",
      "slo_url": "<string>",
      "certificates": [
        "<string>"
      ]
    },
    "sp": {
      "entity_id": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt",
      "acs_url": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/acs",
      "slo_url": "<string>",
      "metadata_url": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/metadata",
      "signing_certificate": "<string>"
    },
    "behavior": {
      "allow_email_account_merge": true,
      "jit_provisioning": true,
      "enforce_login": false,
      "default_redirect_uri": "https://app.acme.com/callback",
      "sync_profile_on_login": false,
      "email_domain_allowlist": [
        "acme.com"
      ]
    },
    "mapping": {
      "email": "email",
      "given_name": "first_name",
      "family_name": "last_name",
      "groups": "groups",
      "custom": {}
    },
    "created_at": "2025-03-15T10:30:00Z",
    "updated_at": "2025-03-15T12:00:00Z"
  }
}
```

--------------------------------

### Create main.go with Firebase and Prelude clients

Source: https://docs.prelude.so/verify/v2/documentation/integrations/firebase

Sets up the HTTP server for the Firebase integration. It initializes the Firebase app and auth client, creates a Prelude client (reading API_TOKEN), and routes POST /send_code and POST /verify endpoints. The Firebase SDK finds the service account via GOOGLE_APPLICATION_CREDENTIALS.

```go
package main

import (
	"context"
	"encoding/json"
	"log"
	"net/http"

	firebase "firebase.google.com/go/v4"
	firebaseauth "firebase.google.com/go/v4/auth"
	prelude "github.com/prelude-so/go-sdk"
)

const addr = ":8080"

func main() {
	ctx := context.Background()

	app, err := firebase.NewApp(ctx, nil)
	if err != nil {
		log.Fatalf("initialize firebase: %v", err)
	}

	authClient, err := app.Auth(ctx)
	if err != nil {
		log.Fatalf("initialize firebase auth: %v", err)
	}

	// NewClient reads the API token from API_TOKEN.
	srv := &server{prelude: prelude.NewClient(), auth: authClient}

	log.Printf("listening on %s", addr)
	log.Fatal(http.ListenAndServe(addr, srv.handler()))
}

// server wires the Prelude and Firebase clients into the HTTP handlers.
type server struct {
	prelude *prelude.Client
	auth    *firebaseauth.Client
}

// handler routes the two endpoints. The mux answers anything else, including a
// known path reached with the wrong method.
func (s *server) handler() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /send_code", s.sendCode)
	mux.HandleFunc("POST /verify", s.verify)
	return mux
}

```

--------------------------------

### Initialize Prelude SDK

Source: https://docs.prelude.so/verify/v2/documentation/quickstart

Initialize the Prelude SDK in Node.js, Python, Go, and Java. Replace API_KEY with your key from the Prelude dashboard (All Services > Configure > Keys). The Java example reads the API token from the API_TOKEN environment variable.

```javascript
import Prelude from "@prelude.so/sdk";

const client = new Prelude({
  apiToken: "API_KEY",
});
```

```python
from prelude_python_sdk import Prelude

client = Prelude(
  api_token="API_KEY",
)
```

```go
package main

import (
	"github.com/prelude-so/go-sdk"
)

func main() {
	client := prelude.NewClient(
    option.WithAPIToken("API_KEY")
  )
}
```

```java
  import so.prelude.sdk.client.PreludeClient;
  import so.prelude.sdk.client.okhttp.PreludeOkHttpClient;

  // Configures using the `API_TOKEN` environment variable
  PreludeClient client = PreludeOkHttpClient.fromEnv();
```

--------------------------------

### Get a flow with Java Unirest

Source: https://docs.prelude.so/watch/v2/api-reference/management/flows/get-flow

Java example using Unirest to fetch a flow. Replace {flow_id} and <token> with your values.

```java
HttpResponse<String> response = Unirest.get("https://api.prelude.dev/v2/watch/management/flows/{flow_id}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Go example to update user profile

Source: https://docs.prelude.so/auth/api-reference/management/users/update-user-profile

Uses net/http to send a PATCH request with a JSON string body. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/users/{userID}/profile"

	payload := strings.NewReader("{\n  \"profile\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Smith\",\n    \"locales\": [\n      \"en-US\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get a flow with PHP cURL

Source: https://docs.prelude.so/watch/v2/api-reference/management/flows/get-flow

PHP example using cURL to fetch a flow. Replace {flow_id} and <token> with your values.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/watch/management/flows/{flow_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Go: Create step-up config

Source: https://docs.prelude.so/auth/api-reference/management/config/stepup/create-stepup-config

Uses net/http to POST the step-up configuration. Reads and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/stepup"

	payload := strings.NewReader("{\n  \"step_keys\": [\n    {\n      \"key\": \"high_value_transaction\",\n      \"description\": \"Triggered for transactions above $10,000\"\n    }\n  ],\n  \"allowed_scopes\": [\n    {\n      \"scope\": \"transfer\"\n    }\n  ],\n  \"jwks_url\": \"https://api.example.com/.well-known/jwks.json\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get a flow with JavaScript fetch

Source: https://docs.prelude.so/watch/v2/api-reference/management/flows/get-flow

JavaScript example using fetch to retrieve a flow. Replace {flow_id} and <token> with your values.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/watch/management/flows/{flow_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Install the Prelude JavaScript SDK with yarn

Source: https://docs.prelude.so/auth/documentation/frontend-sdks/web

Install the @prelude.so/js-sdk package in your frontend project using yarn.

```bash
yarn add @prelude.so/js-sdk

```

--------------------------------

### Initiate OAuth authorization with Go net/http

Source: https://docs.prelude.so/auth/api-reference/frontend/oauth-authorize

Go example using net/http to POST to the OAuth authorize endpoint. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://changeme.session.prelude.dev/v1/session/login/oauth/{provider}/authorize"

	payload := strings.NewReader("{\n  \"redirect_uri\": \"https://example.com/callback\",\n  \"code_challenge\": \"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM\",\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Python requests example for List Users

Source: https://docs.prelude.so/auth/api-reference/management/users/list-users

Uses the requests library to perform a GET request. Prints the response text.

```python
import requests

url = "https://api.prelude.dev/v2/session/apps/{appID}/users"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### 500 Error Response Body for Get JWKS

Source: https://docs.prelude.so/auth/api-reference/frontend/jwks

Example 500 error response body with an internal error code and type.

```json
{
  "code": "internal",
  "type": "internal"
}
```

--------------------------------

### Create Step-Up Config: POST request examples in Go, Java, and Ruby

Source: https://docs.prelude.so/auth/api-reference/management/config/stepup/create-stepup-config

These code examples show how to create a step-up configuration for an application. They send a POST request to the endpoint with the required JSON body, including step_keys, allowed_scopes, and jwks_url. Replace {appID} with the application ID and <token> with a valid authentication token.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/session/apps/{appID}/config/stepup"

	payload := strings.NewReader("{\n  \"step_keys\": [\n    {\n      \"key\": \"high_value_transaction\",\n      \"description\": \"Triggered for transactions above $10,000\"\n    }\n  ],\n  \"allowed_scopes\": [\n    {\n      \"scope\": \"transfer\"\n    }\n  ],\n  \"jwks_url\": \"https://api.example.com/.well-known/jwks.json\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.post("https://api.prelude.dev/v2/session/apps/{appID}/config/stepup")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"step_keys\": [\n    {\n      \"key\": \"high_value_transaction\",\n      \"description\": \"Triggered for transactions above $10,000\"\n    }\n  ],\n  \"allowed_scopes\": [\n    {\n      \"scope\": \"transfer\"\n    }\n  ],\n  \"jwks_url\": \"https://api.example.com/.well-known/jwks.json\"\n}")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/session/apps/{appID}/config/stepup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"step_keys\": [\n    {\n      \"key\": \"high_value_transaction\",\n      \"description\": \"Triggered for transactions above $10,000\"\n    }\n  ],\n  \"allowed_scopes\": [\n    {\n      \"scope\": \"transfer\"\n    }\n  ],\n  \"jwks_url\": \"https://api.example.com/.well-known/jwks.json\"\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Get a flow with Python requests

Source: https://docs.prelude.so/watch/v2/api-reference/management/flows/get-flow

Python example using the requests library to fetch a flow. Replace {flow_id} and <token> with your values.

```python
import requests

url = "https://api.prelude.dev/v2/watch/management/flows/{flow_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Go login example

Source: https://docs.prelude.so/auth/api-reference/frontend/login-email-password

Uses the net/http package to send a POST request with a JSON payload and prints the response body. The payload is constructed as a string reader.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://changeme.session.prelude.dev/v1/session/login/email/password"

	payload := strings.NewReader("{\n  \"identifier\": \"user@example.com\",\n  \"password\": \"S3cur3P@ss!\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Python requests example to retrieve a message template

Source: https://docs.prelude.so/notify/v2/api-reference/management/templates/get-template

Uses the requests library to perform a GET request. Prints the response text.

```python
import requests

url = "https://api.prelude.dev/v2/notify/management/templates/{template_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Create recipe with Go

Source: https://docs.prelude.so/watch/v2/api-reference/management/recipes/create-recipe

Uses net/http to POST the recipe as a JSON string. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/watch/management/recipes"

	payload := strings.NewReader("{\n  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go example for session migration

Source: https://docs.prelude.so/auth/api-reference/frontend/session-migration

Uses net/http to POST the migration payload to /v1/session/migration. Reads and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://changeme.session.prelude.dev/v1/session/migration"

	payload := strings.NewReader("{\n  \"token\": \"legacy-session-token-abc123\",\n  \"code_challenge\": \"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM\",\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### Webhook Setup

Source: https://docs.prelude.so/verify/v2/documentation/webhook

Steps to set up a webhook endpoint to receive events.

```APIDOC
## Webhook Setup

### Description
To start receiving webhook events, implement a handler, pass your endpoint URL to Verification requests, and return a 200 OK response.

### Steps
1. **Implement the handler** - Develop a webhook endpoint function to receive event data POST requests.
2. **Pass the URL** - Add your webhook endpoint URL to your Verification requests to start receiving events.
3. **Return OK** - Return a `200 OK` HTTP response to the POST request to acknowledge receipt. If not, Prelude retries with exponential backoff for up to 2 weeks.

### Retry Behavior
Retries are spaced progressively further apart (1 min, 2 min, 4 min, … up to 12 hours).
```
Tokens:
Raw