> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get workspace settings

> Retrieve workspace settings



## OpenAPI

````yaml api-reference/v01.27.00/openapi-v01.27.00.json get /workspace/{workspace_id}/settings
openapi: 3.0.3
info:
  title: Firma Partner API
  description: >-
    RESTful API for document signing and template management.


    **Authentication**: All endpoints require API key authentication via the
    `Authorization` header. Use your API key directly without any prefix (e.g.,
    `your-api-key`). The Bearer prefix is optional but not required.


    **Security Features**:

    - Input validation using Zod schemas with detailed field-level error
    messages

    - RSA-256 signed JWT tokens for embedded template access


    **Rate Limiting**: Rate limits are tiered based on operation type:

    - Read operations (GET): 200 requests per minute

    - Write operations (POST/PUT/PATCH/DELETE): 120 requests per minute

    - Webhook CRUD operations: 60 requests per minute

    - Webhook test: 10 requests per minute

    - API key regeneration/expiration: 1 request per minute

    - Webhook secret rotation: 1 request per minute


    When rate limits are exceeded, the API returns a `429 Too Many Requests`
    response with headers:

    - `X-RateLimit-Limit`: Maximum requests per minute for this endpoint

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    - `Retry-After`: Seconds until retry is allowed


    **Error Handling**: All errors return structured JSON responses with `error`
    (human-readable message), `code` (machine-readable identifier), and
    `details` (field-level validation errors when applicable).


    **Embedded Template Integration**: The Firma Template Editor can be embedded
    in your application using a standalone JavaScript library.


    ```html

    <!-- Load the Firma Template Editor library -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Generate JWT token via API first

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Initialize editor with JWT token
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    ```
  version: 01.27.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: Production API - Recommended (Current)
  - url: https://api.firma.dev/api/v1
    description: Production API - Planned
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Company information and settings
  - name: Workspaces
    description: Workspace management operations
  - name: Templates
    description: Template management operations
  - name: Signing Requests
    description: Document signing request operations
  - name: Custom Fields
    description: >-
      Custom field definition management for workspaces, templates, and signing
      requests
  - name: Webhooks
    description: Webhook configuration and management
  - name: JWT Management
    description: JWT token generation and revocation for embedded templates
  - name: Workspace Settings
    description: Workspace configuration and settings
  - name: Email Domains
    description: >-
      Email domain setup and verification for sending signing request emails
      from custom domains
  - name: Email Templates
    description: >-
      Email template management for workspace and company-level customization of
      signing request notifications
  - name: Signer Terms
    description: >-
      Custom signer terms-of-service / consent statements, company-level with
      per-language workspace overrides
  - name: Legacy
    description: Deprecated endpoints maintained for backward compatibility
paths:
  /workspace/{workspace_id}/settings:
    get:
      tags:
        - Workspace Settings
      summary: Get workspace settings
      description: Retrieve workspace settings
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Workspace settings retrieved successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Rate limit: 200 requests per minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSettings'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WorkspaceSettings:
      type: object
      properties:
        workspace_id:
          type: string
          format: uuid
        name:
          type: string
          description: Workspace name
        team_email:
          type: string
          format: email
          description: Workspace contact email
        timezone:
          type: string
          description: Workspace timezone
        language:
          type: string
          description: Workspace language for email templates
          enum:
            - en
            - es
            - it
            - pt
            - fr
            - de
            - el
            - ru
            - pl
          default: en
        signing_request_email_header:
          type: string
          description: Custom email header text
        signing_request_email_body:
          type: string
          description: Custom HTML email body
        show_credit_cost_in_editor:
          type: boolean
          description: >-
            Whether to display credit cost in embedded template and signing
            request editors
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Whether signers must verify their email via OTP before accessing
            documents. null = inherit from company setting, true = require OTP,
            false = do not require OTP
        require_terms_acceptance:
          type: boolean
          nullable: true
          description: >-
            Whether signers must accept terms before signing. null inherits the
            company-level setting.
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Disable automatic scrolling to the next required field during
            signing. Inherits from workspace or company if not set.
        show_signature_frame:
          type: boolean
          nullable: true
          description: >-
            Whether to render a visual frame with Signature ID around signatures
            in completed PDFs. null = inherit from company setting (default
            enabled), true = show frame, false = hide frame
        color_primary:
          type: string
          nullable: true
          description: Primary color override (#rrggbb hex). Null to inherit from company.
          example: '#2563eb'
        color_primary_fg:
          type: string
          nullable: true
          description: Primary foreground color override. Null to inherit.
          example: '#ffffff'
        color_background:
          type: string
          nullable: true
          description: Background color override. Null to inherit.
          example: '#0f172a'
        color_foreground:
          type: string
          nullable: true
          description: Foreground/text color override. Null to inherit.
          example: '#ffffff'
        color_card:
          type: string
          nullable: true
          description: Card background color override. Null to inherit.
          example: '#22222a'
        color_border:
          type: string
          nullable: true
          description: Border color override. Null to inherit.
          example: '#3b3b3b'
        color_accent:
          type: string
          nullable: true
          description: Editor chrome accent color. Null to inherit.
          example: '#34eeff'
        color_accent_fg:
          type: string
          nullable: true
          description: Foreground color on accent surfaces. Null to inherit.
          example: '#000000'
        color_canvas:
          type: string
          nullable: true
          description: Editor document-canvas surround color. Null to inherit.
          example: '#0f1419'
        color_muted:
          type: string
          nullable: true
          description: Muted surface color. Null to inherit.
          example: '#22222a'
        color_muted_fg:
          type: string
          nullable: true
          description: Muted text color. Null to inherit.
          example: '#b8b8b8'
        email_local_part:
          type: string
          nullable: true
          description: >-
            The local-part (before the @) of the sender email address. Null to
            inherit from company setting. Only applies when a verified custom
            domain is configured.
          example: signatures
          pattern: ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$
          minLength: 1
          maxLength: 64
        show_partial_watermark:
          type: boolean
          nullable: true
          description: >-
            Show an IN PROGRESS watermark on partial PDF downloads when not all
            signers have completed. Inherits from company settings when null.
        allow_presigning_download:
          type: boolean
          nullable: true
          description: >-
            Allow signers to download the original document before signing.
            Inherits from company settings when null.
        show_qr_code:
          type: boolean
          nullable: true
          description: >-
            Show a QR code on the signing page that allows signers to continue
            on their phone. Inherits from company settings when null.
        signing_button_label_overrides:
          type: object
          nullable: true
          description: >-
            Per-language custom button labels for the signing view. Keys are
            language codes (en, de, etc.), values are objects mapping
            translation keys to custom text. Set to null to use defaults.
          example:
            en:
              common.finish: Confirm
              signing.decline.confirm: I Refuse
            de:
              common.finish: Bestätigen
          additionalProperties:
            type: object
            additionalProperties:
              type: string
              maxLength: 200
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        message:
          type: string
          description: Detailed error description
        details:
          type: object
          description: Additional error details
          additionalProperties: true
  responses:
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    NotFoundError:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: The requested resource was not found
    RateLimitError:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp of reset
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Use your API key directly without any prefix
        (e.g., 'your-api-key'). Bearer prefix is optional but not required.

````