<client>

Summary

Represents an OAuth 2.0 client application registered in PageSeeder.

OAuth clients enable third-party applications to securely access PageSeeder resources on behalf of users or act as service accounts using the OAuth 2.0 authorization framework.

Usage context

Permitted content	<member>
Permitted parent	<clients>

Attributes

This element has the following attributes:

Name	Type	Required	Description
access-token-mag-age			Default max age in seconds of access tokens
app	xs:string	no	App
confidential	xs:boolean	yes	Whether the client can securely store credentials
client-uri	xs:anyURI	no	URI of the client application's home page
created	xs:dateTime	no	Creation timestamp
description	xs:string	no	Human-readable description of the client
grant-type	enum	yes	OAuth 2.0 grant type
id	xs:long	no	Internal PageSeeder ID for the client
identifier	xs:string	no	Unique identifier referred to as `client_id` in Oauth
last-token	xs:dateTime	no	Timestamp when a token was last issued
modified	xs:dateTime	no	Last modification timestamp
name	xs:string	no	Display name of the OAuth client
scope	xs:string	no	Space-separated list of OAuth scopes
redirect-uri
refresh-token-max-age			Default max age in seconds of refresh tokens
requires-consent	`boolean`	no	Whether the client requires explicit user consent
webhook-secret	xs:string	no	Secret for validating webhook signatures

`@access-token-max-age`

The lifetime of access tokens in seconds. After this period, the access token expires and cannot be used.

Common values:

3600 — 1 hour (recommended for most applications)
7200 — 2 hours
86400 — 24 hours (use with caution)

`@app`

An optional application name or category for organizing clients (e.g., "Timesheet", "Mobile App", "Integration").

`@client-uri`

The home page URL of the client application, displayed in consent screens and administrative interfaces for user reference.

`@confidential`

Indicates whether the client is confidential (can securely store a client_secret) or public:

true — Server-side application that can protect credentials
false — Public client (e.g., single-page app, mobile app) that cannot securely store secrets

`@grant-type`

The OAuth 2.0 grant type (flow) the client is authorized to use:

authorization_code — Standard server-side flow with user authorization
client_credentials — Service-to-service authentication (no user context)
refresh_token — Allows obtaining new access tokens using refresh tokens
password — Resource owner password credentials (legacy, use with caution)

`@id`

The PageSeeder database identifier for the OAuth client. It is always an immutable positive long value unique within the PageSeeder instance.

`@identifier`

The OAuth 2.0 client_id — a unique, public identifier for the client application. This is the value clients use when initiating OAuth flows.

Requirements:

Must be unique across all clients
Typically a random alphanumeric string
Maximum length: implementation-dependent (commonly 32-64 characters)

`@name`

A human-readable display name for the OAuth client, shown in consent screens and administrative interfaces.

`@redirect-uri`

The callback URI where PageSeeder redirects users after authorization. Required for authorization_code grant type.

Requirements:

Must be an absolute URI
Must exactly match the URI used during authorization
Should use HTTPS in production environments
Can include query parameters but not fragments

`@refresh-token-max-age`

The lifetime of refresh tokens in seconds:

0 — No refresh token is issued
Positive value — Refresh token expires after this many seconds

Common values:

0 — No refresh token (access token is single-use)
2592000 — 30 days
7776000 — 90 days

`@requires-consent`

Whether the user must explicitly consent to the client accessing their data:

true — User sees a consent screen during authorization
false — Authorization proceeds without explicit consent (typically for trusted first-party apps)

`@scope`

Space-separated list of OAuth 2.0 scopes the client can request:

Standard scopes:

openid — OpenID Connect authentication
profile — Access to user profile information
email — Access to user email address

Example: "openid profile email"

`@webhook-secret`

A shared secret used to sign webhook payloads, allowing the client to verify that webhook calls originate from PageSeeder.

Examples

Example 1: Web Application with Authorization Code Flow

A typical server-side web application that requires user authorization:

XML example

<client id="1"
        identifier="2aa92c5a79baf3fe"
        requires-consent="false"
        confidential="false"
        name="My app"
        grant-type="authorization_code"
        created="2020-03-08T12:34:00+10:00"
        modified="2020-03-10T11:24:00+10:00"
        last-token="2020-05-10T10:28:00+10:00"
        app="Timesheet"
        redirect-uri="http://example.org/login"
        description="My example timesheet"
        client-uri="http://example.org"
        scope="openid profile email"
        access-token-max-age="7200
        refresh-token-max-age="0">
  <member id="45" ...>
    <fullname>John Smith</fullname>
  </member>
</client>

JSON example

{
  "id": "1",
  "identifier": "2aa92c5a79baf3fe",
  "requiresConsent": false,
  "confidential": false,
  "name": "My app",
  "grantType": "authorization_code",
  "accessTokenMaxAge": 7200,
  "refreshTokenMaxAge": 0,
  "created": "2020-03-08T12:34:00+10:00",
  "modified": "2020-03-10T11:24:00+10:00",
  "lastToken": "2020-05-10T10:28:00+10:00",
  "app": "Timesheet",
  "redirectUri": "http://example.org/login",
  "description": "My example timesheet",
  "clientUri": "http://example.org",
  "scope": "openid profile email",
  "member": {
    "id": "45",
    "fullname": "John Smith"
  }
}

Example 2: Service Account (Client Credentials)

A machine-to-machine integration with no user context:

<client id="2"
        identifier="8b9f3e2c1d4a5f67"
        requires-consent="false"
        confidential="true"
        name="Data Sync Service"
        grant-type="client_credentials"
        created="2021-01-15T09:00:00+10:00"
        modified="2021-01-15T09:00:00+10:00"
        last-token="2024-01-10T14:23:00+10:00"
        app="Integration"
        description="Automated data synchronization service"
        access-token-max-age="3600"
        refresh-token-max-age="0">
  <member id="12">
    <fullname>API Administrator</fullname>
  </member>
</client>

Example 3: Public Single-Page Application

A browser-based SPA that cannot securely store secrets:

<client id="3"
        identifier="4c7e9a2f8b1d3e5a"
        requires-consent="true"
        confidential="false"
        name="Document Portal"
        grant-type="authorization_code"
        created="2022-06-20T10:30:00+10:00"
        modified="2023-03-15T16:45:00+10:00"
        last-token="2024-01-12T11:20:00+10:00"
        redirect-uri="https://portal.example.org/auth"
        client-uri="https://portal.example.org"
        scope="openid profile"
        access-token-max-age="3600"
        refresh-token-max-age="0">
  <member id="78">
    <fullname>Portal Admin</fullname>
  </member>
</client>

Schema

XML Schema

<xs:element name="client" type="client"/>

<xs:complexType name="client">
  <xs:sequence>
    <xs:element name="member" type="member-core"/>
  </xs:sequence>
  <xs:attribute name="id" type="id"
                use="required"/>
  <xs:attribute name="identifier"
                type="client-identifier"
                use="required"/>
  <xs:attribute name="requires-consent"
                type="xs:boolean"
                use="required"/>
  <xs:attribute name="confidential"
                type="xs:boolean"
                 use="required"/>
  <xs:attribute name="name"
                type="client-name"
                use="required"/>
  <xs:attribute name="grant-type"
                type="client-granttype"
                use="required"/>
  <xs:attribute name="app"            type="xs:string"/>
  <xs:attribute name="client-uri"     type="xs:anyURI"/>
  <xs:attribute name="created"        type="xs:date"/>
  <xs:attribute name="description"    type="xs:string"/>
  <xs:attribute name="last-token"     type="xs:date"/>
  <xs:attribute name="modified"       type="xs:date"/>
  <xs:attribute name="redirect-uri"   type="xs:anyURI"/>
  <xs:attribute name="scope"          type="xs:string"/>
  <xs:attribute name="webhook-secret" type="xs:string"/>
  <xs:attribute name="access-token-max-age"
                type="positive-long"
                use="required"/>
  <xs:attribute name="refresh-token-max-age"
                type="positive-long"
                use="required"/>
</xs:complexType>

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://dev.pageseeder.com/schemas/client.json",
  "title": "OAuth Client",
  "description": "The JSON representation of an OAuth client in PageSeeder",
  "type": "object",
  "required": [
    "id",
    "identifier",
    "requiresConsent",
    "confidential",
    "name",
    "grantType",
    "accessTokenMaxAge",
    "refreshTokenMaxAge"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Internal PageSeeder ID for the client"
    },
    "identifier": {
      "type": "string",
      "description": "Unique identifier referred to as client_id in OAuth"
    },
    "requiresConsent": {
      "type": "boolean",
      "description": "Whether the client requires user consent"
    },
    "confidential": {
      "type": "boolean",
      "description": "Whether the client is confidential"
    },
    "name": {
      "type": "string",
      "description": "Name of the OAuth client"
    },
    "grantType": {
      "type": "string",
      "description": "OAuth grant type",
      "enum": ["authorization_code", "client_credentials", "refresh_token", "password"]
    },
    "accessTokenMaxAge": {
      "type": "integer",
      "minimum": 0,
      "description": "Default max age in seconds of access tokens"
    },
    "refreshTokenMaxAge": {
      "type": "integer",
      "minimum": 0,
      "description": "Default max age in seconds of refresh tokens"
    },
    "app": {
      "type": "string",
      "description": "Application name"
    },
    "clientUri": {
      "type": "string",
      "format": "uri",
      "description": "URI of the client application"
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp"
    },
    "description": {
      "type": "string",
      "description": "Description of the OAuth client"
    },
    "lastToken": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of last token issuance"
    },
    "modified": {
      "type": "string",
      "format": "date-time",
      "description": "Last modification timestamp"
    },
    "redirectUri": {
      "type": "string",
      "format": "uri",
      "description": "Redirect URI for OAuth flow"
    },
    "scope": {
      "type": "string",
      "description": "OAuth scopes (space-separated)"
    },
    "webhookSecret": {
      "type": "string",
      "description": "Secret for webhook validation"
    },
    "member": {
      "type": "object",
      "description": "Member associated with the client",
      "properties": {
        "id": {
          "type": "string"
        },
        "fullname": {
          "type": "string"
        }
      }
    }
  },
  "additionalProperties": false
}

Compatibility

Stable since initial API release. No breaking changes.

The grant-type attribute values follow OAuth 2.0 specifications
Token max age values are expressed in seconds following OAuth 2.0 conventions
The identifier attribute corresponds to the standard OAuth 2.0 client_id parameter

Created on 6 January 2017, last edited on 8 September 2026 at 21:58