Create an app with an organization secret

This guide shows how to create a Privy app with an organization secret. Use this flow to provision apps for an existing organization without the Dashboard UI.

Before you begin

Prerequisites:

An existing Privy organization
The organization_secrets feature enabled for that organization
Admin access in the Privy Dashboard
The organization ID
An organization secret for that organization

Create an organization secret

In the Privy Dashboard, open the organization settings and create an organization secret.

Privy does not store organization secrets. Copy the value at creation time and store it in a secret manager.

Notes:

Privy uses the organization ID for API authentication.
Each organization can have at most 2 active organization secrets at a time.
A secret can include an optional P-256 signing public key.
When a signing key is present, every request with that secret must include a valid request signature.

Create an app

Send a POST request to:

https://auth.privy.io/api/v1/organizations/{organization_id}/apps

The request must include:

Authorization: Basic <base64(organization_id:organization_secret)>
privy-organization-id: <organization_id>
Content-Type: application/json

Example with cURL

export PRIVY_ORGANIZATION_ID="org_123"
export PRIVY_ORGANIZATION_SECRET="organization-secret-value"

curl --request POST \
  --url "https://auth.privy.io/api/v1/organizations/${PRIVY_ORGANIZATION_ID}/apps" \
  --header "Authorization: Basic $(printf '%s:%s' "$PRIVY_ORGANIZATION_ID" "$PRIVY_ORGANIZATION_SECRET" | base64)" \
  --header "privy-organization-id: ${PRIVY_ORGANIZATION_ID}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My Programmatic App"
  }'

Example response

{
  "app_id": "clx123exampleapp",
  "app_name": "My Programmatic App",
  "app_secret": "privy_app_secret_123"
}

Store the returned app_secret immediately. Like app secrets created in the Dashboard, it cannot be recovered later.

List apps for an organization

List all apps in the organization with:

curl --request GET \
  --url "https://auth.privy.io/api/v1/organizations/${PRIVY_ORGANIZATION_ID}/apps" \
  --header "Authorization: Basic $(printf '%s:%s' "$PRIVY_ORGANIZATION_ID" "$PRIVY_ORGANIZATION_SECRET" | base64)" \
  --header "privy-organization-id: ${PRIVY_ORGANIZATION_ID}"

Example response:

{
  "data": [
    {
      "app_id": "clx123exampleapp",
      "app_name": "My Programmatic App"
    }
  ]
}

Configure the app

After app creation, use the returned app_id and app_secret to configure the app. Use this app update endpoint:

https://auth.privy.io/api/v1/apps/{app_id}

This request uses app credentials, not organization credentials. Include:

Authorization: Basic <base64(app_id:app_secret)>
privy-app-id: <app_id>
Content-Type: application/json

export PRIVY_APP_ID="app-id"
export PRIVY_APP_SECRET="app-secret"

curl --request POST \
  --url "https://auth.privy.io/api/v1/apps/${PRIVY_APP_ID}" \
  --header "Authorization: Basic $(printf '%s:%s' "$PRIVY_APP_ID" "$PRIVY_APP_SECRET" | base64)" \
  --header "privy-app-id: ${PRIVY_APP_ID}" \
  --header "Content-Type: application/json" \
  --data '{
    "email_auth": true,
    "sms_auth": true
  }'

Example response

{
  "id": "clx123exampleapp",
  "email_auth": true,
  "sms_auth": true
}

POST /api/v1/apps/{app_id} is a broad legacy app-settings endpoint. For this flow, the relevant fields are email_auth and sms_auth.

SMS login cannot be enabled when SMS transaction MFA is already enabled for the app. SMS and WhatsApp are also mutually exclusive.

Signed requests

If the organization secret has a signing public key, include two extra headers on every request:

privy-request-expiry: a future Unix timestamp in milliseconds
privy-authorization-signature: a base64-encoded P-256 signature over the canonical request payload

Sign this canonical JSON payload:

{
  "version": 1,
  "method": "POST",
  "url": "https://auth.privy.io/api/v1/organizations/org_123/apps",
  "body": {
    "name": "My Programmatic App"
  },
  "headers": {
    "privy-organization-id": "org_123",
    "privy-request-expiry": "1760000000000"
  }
}

Node.js example

This example uses canonicalize. It matches Privy’s canonical request format.

import canonicalize from 'canonicalize';
import crypto from 'node:crypto';

const organizationId = process.env.PRIVY_ORGANIZATION_ID!;
const organizationSecret = process.env.PRIVY_ORGANIZATION_SECRET!;
const privateKeyPem = process.env.PRIVY_SIGNING_PRIVATE_KEY!;

const url = `https://auth.privy.io/api/v1/organizations/${organizationId}/apps`;
const requestExpiry = String(Date.now() + 60_000);
const body = {name: 'My Programmatic App'};

const payload = canonicalize({
  version: 1,
  method: 'POST',
  url,
  body,
  headers: {
    'privy-organization-id': organizationId,
    'privy-request-expiry': requestExpiry
  }
});

if (!payload) {
  throw new Error('Failed to canonicalize request payload');
}

const signer = crypto.createSign('SHA256');
signer.update(payload);
signer.end();

const signature = signer.sign(privateKeyPem, 'base64');
const basicAuth = Buffer.from(`${organizationId}:${organizationSecret}`).toString('base64');

const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${basicAuth}`,
    'Content-Type': 'application/json',
    'privy-organization-id': organizationId,
    'privy-request-expiry': requestExpiry,
    'privy-authorization-signature': signature
  },
  body: JSON.stringify(body)
});

console.log(await response.json());

Troubleshooting

If the organization ID in Basic auth does not match the organization ID in the URL, Privy rejects the request.
If privy-organization-id is missing or does not match the authenticated organization, Privy rejects the request.
A revoked organization secret causes Privy to reject the request.
Enabling request signing on a secret causes Privy to reject requests without a valid privy-authorization-signature.

​Before you begin

​Create an organization secret

​Create an app

​Example with cURL

​Example response

​List apps for an organization

​Configure the app

​Enable email and phone login methods

​Example response

​Signed requests

​Node.js example

​Troubleshooting

Before you begin

Create an organization secret

Create an app

Example with cURL

Example response

List apps for an organization

Configure the app

Enable email and phone login methods

Example response

Signed requests

Node.js example

Troubleshooting