OAuthClient

Defines a registered OAuth client application.

This object can be configured from the WebUI under Management › Directory › OAuth Clients

Fields

clientId

Type: String · required

Unique identifier of the OAuth client. It may be the HTTPS URL of a Client ID Metadata Document to pre-register an application that publishes one. Identifiers generated by this server never start with https://.

description

Type: String?

Description of the OAuth client

contacts

Type: Set<EmailAddress>

Contact email addresses for the OAuth client

secret

Type: String? · secret

Secret value of the OAuth client

createdAt

Type: UTCDateTime · read-only · server-set

Creation date of the OAuth client

expiresAt

Type: UTCDateTime?

Expiration date of the OAuth client

memberTenantId

Type: Id<Tenant>? · enterprise

Identifier for the tenant this OAuth client belongs to

redirectUris

Type: Set<Uri>

List of redirect URIs for the OAuth client

postLogoutRedirectUris

Type: Set<Uri>

URIs the client may ask to return to after signing out (OpenID Connect RP-Initiated Logout). A requested URI must match an entry exactly.

logo

Type: String?

URL or base64-encoded image representing the OAuth client

firstParty

Type: Boolean · default: false

Trusted application. Tokens issued to it carry the account’s full permissions instead of being limited to the requested scopes; the user is still asked for consent. At least one redirect URI is required. Only a superuser can enable it. Stalwart’s own web applications do not need this setting: they are recognized from their installed bundle.

scopes

Type: Set<OAuthScope>

Services the client may request access to. Ignored for first-party clients. When empty, the client can only request sign-in (openid).

grantTypes

Type: Set<OAuthGrantType> · default: {"authorizationCode":true,"refreshToken":true}

OAuth grant types the client may use. The device authorization grant is only available when listed here.

JMAP API

The OAuthClient object is available via the urn:stalwart:jmap capability.

x:OAuthClient/get

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

This method requires the sysOAuthClientGet permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:OAuthClient/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:OAuthClient/set

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

Supports the following operations in a single call: create, update, destroy.

Create

This operation requires the sysOAuthClientCreate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:OAuthClient/set",
          {
            "create": {
              "new1": {
                "clientId": "Example",
                "contacts": {},
                "postLogoutRedirectUris": {},
                "redirectUris": {},
                "scopes": {}
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysOAuthClientUpdate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:OAuthClient/set",
          {
            "update": {
              "id1": {
                "clientId": "updated value"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Destroy

This operation requires the sysOAuthClientDestroy permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:OAuthClient/set",
          {
            "destroy": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:OAuthClient/query

This is a standard Foo/query method as defined in RFC 8620, Section 5.5.

This method requires the sysOAuthClientQuery permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:OAuthClient/query",
          {
            "filter": {
              "text": "example"
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

The x:OAuthClient/query filter argument accepts the following conditions (combinable with AnyOf / AllOf / Not per RFC 8620):

Condition	Kind
text	text
clientId	text
memberTenantId	id of Tenant

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get OAuthClient id1

Create

stalwart-cli create OAuthClient \
  --field clientId=Example \
  --field 'contacts={}' \
  --field 'redirectUris={}' \
  --field 'postLogoutRedirectUris={}' \
  --field 'scopes={}'

Query

stalwart-cli query OAuthClient
stalwart-cli query OAuthClient --where text=example

Update

stalwart-cli update OAuthClient id1 --field clientId='updated value'

Delete

stalwart-cli delete OAuthClient --ids id1

Enums

OAuthScope

Value	Label
mail	Mail (IMAP, POP3, SMTP submission, ManageSieve, JMAP Mail)
contacts	Contacts (CardDAV, JMAP Contacts)
calendars	Calendars (CalDAV, JMAP Calendars)
files	Files (WebDAV, JMAP File Storage)

OAuthGrantType

Value	Label
authorizationCode	Authorization code
refreshToken	Refresh token
deviceCode	Device authorization