Management API

The Management API provides CRUD operations for all Paylent resources. It follows the JSON:API specification and is available at /api/ under each environment’s subdomain.

Users

GET    /api/users          # List users
GET    /api/users/:id      # Get user
POST   /api/users          # Create user (create_with_password)
PATCH  /api/users/:id      # Update user
DELETE /api/users/:id      # Delete user

Create User

{
  "data": {
    "type": "user",
    "attributes": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "password": "secure_password",
      "password_confirmation": "secure_password"
    }
  }
}

Sessions

GET    /api/sessions              # List sessions
GET    /api/sessions/:id          # Get session
POST   /api/sessions              # Create session
PATCH  /api/sessions/:id/touch    # Update last activity
PATCH  /api/sessions/:id/revoke   # Revoke session
DELETE /api/sessions/:id          # Delete session

Sessions track IP address, user agent, last activity, expiry, and revocation status.

Roles & Permissions

GET    /api/roles            # List roles
GET    /api/roles/:id        # Get role (includes user_count, permission_count)
POST   /api/roles            # Create role
PATCH  /api/roles/:id        # Update role
DELETE /api/roles/:id        # Delete role

GET    /api/permissions      # List permissions
POST   /api/permissions      # Create permission
PATCH  /api/permissions/:id  # Update permission
DELETE /api/permissions/:id  # Delete permission

Assign Permission to Role

POST /api/role-permissions

{
  "data": {
    "type": "role_permission",
    "attributes": {},
    "relationships": {
      "role": { "data": { "type": "role", "id": "ROLE_ID" } },
      "permission": { "data": { "type": "permission", "id": "PERM_ID" } }
    }
  }
}

Assign Role to User

POST /api/user-roles

{
  "data": {
    "type": "user_role",
    "attributes": {},
    "relationships": {
      "user": { "data": { "type": "user", "id": "USER_ID" } },
      "role": { "data": { "type": "role", "id": "ROLE_ID" } }
    }
  }
}

OAuth Clients

GET    /api/clients          # List clients
GET    /api/clients/:id      # Get client
POST   /api/clients          # Register client
PATCH  /api/clients/:id      # Update client
DELETE /api/clients/:id      # Delete client

Register Client

{
  "data": {
    "type": "client",
    "attributes": {
      "name": "My App",
      "client_type": "confidential",
      "redirect_uris": ["https://myapp.example.com/callback"],
      "grant_types": ["authorization_code", "refresh_token"],
      "token_format": "jwt",
      "first_party": false
    }
  }
}

Field	Values
client_type	confidential, public
grant_types	authorization_code, client_credentials, refresh_token
token_format	jwt, opaque
redirect_uris	Up to 10 URLs

Resource Servers

GET    /api/resource-servers          # List resource servers
GET    /api/resource-servers/:id      # Get resource server
POST   /api/resource-servers          # Create resource server
PATCH  /api/resource-servers/:id      # Update resource server
DELETE /api/resource-servers/:id      # Delete resource server

System resource servers (like the Management API) cannot be updated or deleted.

Scopes

Scopes belong to a resource server. See API Resources for details.

GET    /api/scopes          # List scopes
GET    /api/scopes/:id      # Get scope
POST   /api/scopes          # Create scope
PATCH  /api/scopes/:id      # Update scope
DELETE /api/scopes/:id      # Delete scope

Create Scope

{
  "data": {
    "type": "scope",
    "attributes": {
      "name": "read:users",
      "description": "Read user profiles"
    },
    "relationships": {
      "resource_server": {
        "data": { "type": "resource_server", "id": "RESOURCE_SERVER_ID" }
      }
    }
  }
}

Signing Keys

GET    /api/signing-keys              # List signing keys
GET    /api/signing-keys/:id          # Get signing key
POST   /api/signing-keys              # Generate new key pair
PATCH  /api/signing-keys/:id/deactivate  # Deactivate key
DELETE /api/signing-keys/:id          # Delete key

Keys are RSA256. When a new key is generated, it automatically becomes the primary signing key. Deactivating the current primary promotes the next active key.

Organizations

GET    /api/organizations          # List organizations
GET    /api/organizations/:id      # Get organization (includes member_count)
POST   /api/organizations          # Create organization
DELETE /api/organizations/:id      # Delete organization

Memberships

GET    /api/memberships          # List memberships
GET    /api/memberships/:id      # Get membership
POST   /api/memberships          # Create membership
DELETE /api/memberships/:id      # Delete membership

Each user can have one membership per organization.

Invitations

GET    /api/invitations          # List invitations
GET    /api/invitations/:id      # Get invitation
POST   /api/invitations          # Create invitation
PATCH  /api/invitations/:id/revoke  # Revoke invitation
DELETE /api/invitations/:id      # Delete invitation

Invitations include email, role_ids, status (pending/accepted/declined/revoked), and expires_at. Acceptance and decline are handled via separate endpoints:

POST /invitations/:id/accept
POST /invitations/:id/decline

Connections

GET    /api/connections          # List connections
GET    /api/connections/:id      # Get connection
POST   /api/connections          # Create connection
PATCH  /api/connections/:id      # Update connection
DELETE /api/connections/:id      # Delete connection

See Connections (SSO) for details on supported providers and configuration.

Create Connection

{
  "data": {
    "type": "connection",
    "attributes": {
      "strategy": "google",
      "display_name": "Google",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "scopes": "openid email profile"
    }
  }
}

Field	Values
strategy	google, microsoft, github, facebook, discord, gitlab, slack, linkedin, bitbucket, auth0, oidc
discovery_url	Required for oidc and auth0 strategies
enforce_sso	true / false (default: false)

Webhooks

GET    /api/webhooks                     # List webhooks
GET    /api/webhooks/:id                 # Get webhook
POST   /api/webhooks                     # Create webhook
PATCH  /api/webhooks/:id                 # Update webhook
PATCH  /api/webhooks/:id/rotate_secret   # Rotate signing secret
DELETE /api/webhooks/:id                 # Delete webhook

See Webhooks for event types and payload format.

Create Webhook

{
  "data": {
    "type": "webhook",
    "attributes": {
      "name": "User sync",
      "url": "https://myapp.example.com/webhooks",
      "events": ["user.created", "user.updated"],
      "active": true
    }
  }
}

The signing_secret is included in the create response. Save it immediately — it cannot be retrieved again.

Actions

GET    /api/actions          # List actions
GET    /api/actions/:id      # Get action
POST   /api/actions          # Create action
PATCH  /api/actions/:id      # Update action
DELETE /api/actions/:id      # Delete action

See Actions for trigger types and code examples.

Create Action

{
  "data": {
    "type": "action",
    "attributes": {
      "name": "Add custom claims",
      "trigger": "pre_token",
      "code": "export default async function(event) {\n  return { claims: event.claims };\n}",
      "enabled": true
    }
  }
}

Field	Values
trigger	pre_token, post_login
code	JavaScript/TypeScript (max 64 KB)
enabled	true / false (default: true)

Only one action per trigger per environment is allowed.