Stalwart Auth overview API

openapi: 3.1.0
info:
  title: Stalwart Auth overview API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 21 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Stalwart has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 7
    documentation: 37
    pages-with-code: 12
    pages-read: 21
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://stalw.art/docs/auth/oauth/authorization
  - https://stalw.art/docs/auth/oauth/clients
  - https://stalw.art/docs/auth/oauth/consent
  - https://stalw.art/docs/auth/oauth/register-client
  - https://stalw.art/docs/auth/oauth/tokens
  - https://stalw.art/docs/auth/scim/configuration
  - https://stalw.art/docs/auth/scim/endpoints
  - https://stalw.art/docs/auth/scim/providers/okta
  x-docs-section: auth
servers:
- url: https://get.stalw.art
paths:
  /Groups:
    get:
      operationId: get_Groups
      tags:
      - Groups
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_Groups
      tags:
      - Groups
      summary: Create a new group via SCIM
      description: Creates a SCIM group; groups are placed in the provisioning account’s domain, which must have allowScimProvisioning enabled.
      x-source: https://stalw.art/docs/auth/scim/configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGroupsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostGroupsResponse'
      x-evidence:
        kind: documentation
  /Groups/{id}:
    delete:
      operationId: delete_Groups_id
      tags:
      - Groups
      summary: Okta can create, update and suspend Stalwart accounts as users join, change and leave the organisation.
      x-source: https://stalw.art/docs/auth/scim/providers/okta
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_Groups_id
      tags:
      - Groups
      summary: Okta can create, update and suspend Stalwart accounts as users join, change and leave the organisation.
      x-source: https://stalw.art/docs/auth/scim/providers/okta
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /Users:
    get:
      operationId: get_Users
      tags:
      - Users
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_Users
      tags:
      - Users
      summary: Create a new user via SCIM
      description: Creates a SCIM user; a POST /Users whose userName is in an enabled domain succeeds, otherwise a 400 Bad Request with scimType
        invalidValue is returned.
      x-source: https://stalw.art/docs/auth/scim/configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUsersRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUsersResponse'
      x-evidence:
        kind: documentation
  /auth/device:
    post:
      operationId: post_auth_device
      tags:
      - Auth
      summary: Device authorization flow
      x-source: https://stalw.art/docs/auth/oauth/authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAuthDeviceRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthDeviceResponse'
      x-evidence:
        kind: documentation
  /auth/introspect:
    post:
      operationId: post_auth_introspect
      tags:
      - Auth
      summary: Introspection
      description: 'Returns token state according to RFC 7662. Active tokens include details; inactive tokens report active: false.'
      x-source: https://stalw.art/docs/auth/oauth/tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAuthIntrospectRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthIntrospectResponse'
      x-evidence:
        kind: documentation
  /auth/register:
    post:
      operationId: post_auth_register
      tags:
      - Auth
      summary: 'Dynamic clients: register a client via POST /auth/register'
      x-source: https://stalw.art/docs/auth/oauth/clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAuthRegisterRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthRegisterResponse'
      x-evidence:
        kind: documentation
  /auth/revoke:
    post:
      operationId: post_auth_revoke
      tags:
      - Auth
      summary: POST /auth/revoke
      x-source: https://stalw.art/docs/auth/oauth/tokens
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://mail.example.com/auth/revoke \\ -d token=<refresh token> \\ -d client_id=swc1.<encoded registration> \\\
          \x7F -d client_id=swc1. \"> \n A successful revocation deletes the whole grant, with the same effect as deleting the application in\
          \ Connected Applications: every access and refresh token of the grant stops working. The response is 200 OK with an empty body. \n The\
          \ same response is ret"
  /auth/token:
    post:
      operationId: post_auth_token
      tags:
      - Auth
      summary: POST /auth/token
      x-source: https://stalw.art/docs/auth/oauth/authorization
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://mail.example.com/auth/token \\ -d grant_type=authorization_code \\ -d code=<code> \\ -d redirect_uri=http://127.0.0.1:49152/callback\
          \ \\ -d client_id=swc1.<encoded registration> \\ -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \\\x7F -d redirect_uri=http://127.0.0.1:49152/callback\
          \ \\\x7F -d client_id=swc1. \\\x7F -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"> \n Th"
  /jmap:
    post:
      operationId: post_jmap
      tags:
      - Jmap
      summary: POST /jmap
      x-source: https://stalw.art/docs/auth/oauth/consent
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://mail.example.com/jmap/ \\ -H ' Authorization: Bearer <token> ' \\ -H ' Content-Type: application/json '\
          \ \\ -d ' { \"using\": [\"urn:ietf:params:jmap:core\", \"urn:stalwart:jmap\"], \"methodCalls\": [ [\"x:OAuthGrant/query\", {\"filter\"\
          : {\"accountId\": \"c\"}}, \"0\"], [\"x:OAuthGrant/get\", {\"#ids\": {\"resultOf\": \"0\", \"name\": \"x:OAuthGrant/query\", \"path\"\
          : \"/ids\"}}, \"1\"] ] } ' ' \\\x7F -H 'Content-Type:"
  /jmap/:
    get:
      operationId: get_jmap
      tags:
      - Jmap
      summary: Registering an application
      description: Not documented on this page; operation omitted.
      x-source: https://stalw.art/docs/auth/oauth/register-client
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_jmap
      tags:
      - Jmap
      summary: Registering an application
      x-source: https://stalw.art/docs/auth/oauth/register-client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostJmapRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostJmapResponse'
      x-evidence:
        kind: documentation
  /scim/v2/.search:
    post:
      operationId: post_scim_v2_search
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim/v2/Bulk:
    post:
      operationId: post_scim_v2_Bulk
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim/v2/Groups/.search:
    post:
      operationId: post_scim_v2_Groups_search
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim/v2/Schemas:
    get:
      operationId: get_scim_v2_Schemas
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim/v2/ServiceProviderConfig:
    get:
      operationId: get_scim_v2_ServiceProviderConfig
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim/v2/Users:
    get:
      operationId: get_scim_v2_Users
      tags:
      - Scim
      summary: List SCIM users
      description: Returns a list of users; requires a Bearer token with scimAccess and sysAccountGet permissions.
      x-source: https://stalw.art/docs/auth/scim/configuration
      parameters:
      - name: count
        in: query
        required: false
        schema:
          type: string
        description: Maximum number of results to return.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScimV2UsersResponse'
      x-evidence:
        kind: documentation
  /scim/v2/Users/.search:
    post:
      operationId: post_scim_v2_Users_search
      tags:
      - Scim
      summary: Endpoints and protocol support
      x-source: https://stalw.art/docs/auth/scim/endpoints
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
security:
- bearer: []
components:
  schemas:
    PostGroupsRequest:
      type: object
      properties:
        displayName:
          type: string
          description: The name of the group.
      required:
      - displayName
    PostGroupsResponse:
      type: object
      properties:
        Location:
          type: string
          description: URL of the created group resource.
    PostUsersRequest:
      type: object
      properties:
        userName:
          type: string
          description: The unique user name (must belong to an enabled domain).
        displayName:
          type: string
          description: Human‑readable name of the user.
      required:
      - userName
    PostUsersResponse:
      type: object
      properties:
        Location:
          type: string
          description: URL of the created user resource.
    PostAuthDeviceRequest:
      type: object
      properties:
        client_id:
          type: string
          description: Client identifier
        scope:
          type: string
          description: Requested scopes
      required:
      - client_id
    PostAuthDeviceResponse:
      type: object
      properties:
        device_code:
          type: string
        user_code:
          type: string
        verification_uri:
          type: string
        verification_uri_complete:
          type: string
        expires_in:
          type: integer
        interval:
          type: integer
    PostAuthIntrospectRequest:
      type: object
      properties:
        token:
          type: string
          description: The token whose state is being queried
      required:
      - token
    PostAuthIntrospectResponse:
      type: object
      properties:
        active:
          type: boolean
          description: True if the token is active, false otherwise
        username:
          type: string
          description: Owning account name (present when active)
        sub:
          type: string
          description: Subject identifier of the account (present when active)
        scope:
          type: string
          description: Granted scope of the token (present when active)
        client_id:
          type: string
          description: Client identifier of the grant (present when active)
        token_type:
          type: string
          description: Either "bearer" for access tokens or "refresh_token" for refresh tokens
    PostAuthRegisterRequest:
      type: object
      properties:
        name:
          type: string
          description: Application name to register
        redirectUris:
          type: object
          description: Map of redirect URI strings to boolean true
        scopes:
          type: object
          description: Map of requested scope names to boolean true
      required:
      - name
      - redirectUris
    PostAuthRegisterResponse:
      type: object
      properties:
        clientId:
          type: string
          description: Generated client identifier (swc1.)
    PostJmapRequest:
      type: object
      properties:
        using:
          type: array
        methodCalls:
          type: array
      required:
      - using
      - methodCalls
    PostJmapResponse:
      type: object
      properties:
        methodResponses:
          type: array
    GetScimV2UsersResponse:
      type: object
      properties:
        Resources:
          type: array
          description: Array of user objects.
        totalResults:
          type: integer
          description: Total number of matching users.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
tags:
- name: Auth
- name: Groups
- name: Jmap
- name: Scim
- name: Users