Applications

Applications are the foundation of Zyphr Auth-as-a-Service. Each application has its own user pool, API keys, and configuration. You can manage applications through the Dashboard or the API.

Create an Application

Via Dashboard

1. Navigate to Applications in the sidebar
2. Click Create Application
3. Enter an application name (the slug is auto-generated)
4. Configure session and token durations
5. Add allowed origins and redirect URIs
6. Click Create
7. Copy the secret key — it is only shown once

Via API

curl -X POST https://api.zyphr.dev/v1/applications \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SaaS App",
    "slug": "my-saas-app",
    "session_duration_minutes": 60,
    "refresh_token_duration_days": 30,
    "allowed_origins": ["https://myapp.com"],
    "redirect_uris": ["https://myapp.com/auth/callback"]
  }'

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${dashboardToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My SaaS App',
    slug: 'my-saas-app',
    session_duration_minutes: 60,
    refresh_token_duration_days: 30,
    allowed_origins: ['https://myapp.com'],
    redirect_uris: ['https://myapp.com/auth/callback'],
  }),
});

Parameters

Parameter	Type	Required	Description
name	string	Yes	Application name (max 255 chars)
slug	string	No	URL-friendly identifier. Lowercase, numbers, hyphens only (max 100 chars). Auto-generated if omitted.
session_duration_minutes	number	No	Access token lifetime (1–43,200 min / 30 days). Default: 60.
refresh_token_duration_days	number	No	Refresh token lifetime (1–365 days). Default: 30.
allowed_origins	string[]	No	CORS origins for client-side auth
redirect_uris	string[]	No	Allowed OAuth redirect URIs

Response

{
  "data": {
    "id": "app_abc123",
    "workspace_id": "ws_xyz",
    "name": "My SaaS App",
    "slug": "my-saas-app",
    "public_key": "za_pub_xxxx",
    "secret_key": "za_sec_xxxx",
    "session_duration_minutes": 60,
    "refresh_token_duration_days": 30,
    "allowed_origins": ["https://myapp.com"],
    "redirect_uris": ["https://myapp.com/auth/callback"],
    "status": "active",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z",
    "environments": [
      {
        "id": "env_live_123",
        "mode": "live",
        "public_key": "za_pub_live_xxxx",
        "secret_key": "za_sec_live_xxxx",
        "created_at": "2025-01-15T10:00:00Z"
      },
      {
        "id": "env_test_456",
        "mode": "test",
        "public_key": "za_pub_test_xxxx",
        "secret_key": "za_sec_test_xxxx",
        "created_at": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "meta": {
    "warning": "Save all secret keys securely. They will not be shown again."
  }
}

caution

Secret keys are only returned on creation and during key rotation. Store them securely in your environment variables or secrets manager.

Viewing Applications

Via Dashboard

Navigate to Applications in the sidebar to see all applications with their name, slug, status, user count, and creation date. Click on any application to view its full configuration.

Via API

# List all applications
curl https://api.zyphr.dev/v1/applications \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

# Get a specific application
curl https://api.zyphr.dev/v1/applications/app_abc123 \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Returns all applications in the workspace with end_users_count for each. When fetching a specific application, secret keys are not included — only public keys are shown.

Update Application

Via Dashboard

1. Navigate to Applications and click on an application
2. Edit the name, session duration, allowed origins, or redirect URIs
3. Click Save

Via API

curl -X PATCH https://api.zyphr.dev/v1/applications/app_abc123 \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated App Name",
    "session_duration_minutes": 120,
    "allowed_origins": ["https://myapp.com", "https://staging.myapp.com"]
  }'

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications/app_abc123', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${dashboardToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Updated App Name',
    session_duration_minutes: 120,
  }),
});

Supports partial updates — only include fields you want to change. Requires owner or admin role.

Delete Application

Via Dashboard

1. Navigate to Applications and click on an application
2. Click Delete Application
3. Confirm the deletion

Via API

curl -X DELETE https://api.zyphr.dev/v1/applications/app_abc123 \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications/app_abc123', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${dashboardToken}` },
});

danger

Deleting an application removes all associated end users, sessions, and data. This action cannot be undone.

Environments

Each application automatically gets live and test environments with independent API keys. Use test keys during development and live keys in production.

List Environments

curl https://api.zyphr.dev/v1/applications/app_abc123/environments \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications/app_abc123/environments', {
  headers: { 'Authorization': `Bearer ${dashboardToken}` },
});

Rotate Environment Keys

Rotate the secret key for a specific environment without affecting the other:

curl -X POST https://api.zyphr.dev/v1/applications/app_abc123/environments/live/rotate-keys \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch(
  'https://api.zyphr.dev/v1/applications/app_abc123/environments/live/rotate-keys',
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${dashboardToken}` },
  }
);
// Response includes the new secret_key — save it immediately

The mode parameter in the URL must be either live or test.

Key Rotation (Legacy)

Rotate the legacy application-level secret key:

curl -X POST https://api.zyphr.dev/v1/applications/app_abc123/rotate-keys \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch(
  'https://api.zyphr.dev/v1/applications/app_abc123/rotate-keys',
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${dashboardToken}` },
  }
);

tip

Prefer using environment-specific key rotation over legacy key rotation. Environment keys let you rotate live and test independently.

End User Management (Admin)

Application owners can manage end users through the dashboard API.

List End Users

curl https://api.zyphr.dev/v1/applications/app_abc123/users \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications/app_abc123/users', {
  headers: { 'Authorization': `Bearer ${dashboardToken}` },
});

Get End User

curl https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz', {
  headers: { 'Authorization': `Bearer ${dashboardToken}` },
});

Delete End User

curl -X DELETE https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Node.js

const response = await fetch(
  'https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz',
  {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${dashboardToken}` },
  }
);

Get User OAuth Connections

View OAuth connections for a specific user:

curl https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz/oauth-connections \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Delete User OAuth Connection

Remove a specific OAuth provider connection:

curl -X DELETE https://api.zyphr.dev/v1/applications/app_abc123/users/usr_xyz/oauth-connections/google \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT"

Authentication Requirements

Endpoint Group	Auth Required	Roles
Create/update/delete applications	Dashboard JWT	Owner, Admin
List/get applications	Dashboard JWT	Any
Key rotation	Dashboard JWT	Owner, Admin
End user management	Dashboard JWT	Any

Endpoint Reference

Method	Endpoint	Description
POST	/v1/applications	Create application
GET	/v1/applications	List applications
GET	/v1/applications/:id	Get application
PATCH	/v1/applications/:id	Update application
DELETE	/v1/applications/:id	Delete application
POST	/v1/applications/:id/rotate-keys	Rotate legacy secret key
GET	/v1/applications/:id/environments	List environments
POST	/v1/applications/:id/environments/:mode/rotate-keys	Rotate environment secret key
GET	/v1/applications/:id/users	List end users
GET	/v1/applications/:id/users/:userId	Get end user
DELETE	/v1/applications/:id/users/:userId	Delete end user
GET	/v1/applications/:id/users/:userId/oauth-connections	List user OAuth connections
DELETE	/v1/applications/:id/users/:userId/oauth-connections/:provider	Delete user OAuth connection
POST	/v1/applications/:id/users/:userId/impersonate	Start impersonation
DELETE	/v1/applications/:id/impersonation/:impersonationId	End impersonation
GET	/v1/applications/:id/impersonation	List active impersonations
GET	/v1/applications/:id/users/:userId/impersonation-history	Get impersonation history

See Security Features for impersonation documentation and Security Features for lockout management.