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